Konfigurowanie pól tekstowych

TextField umożliwia użytkownikom wpisywanie i modyfikowanie tekstu. Możesz używać 2 rodzajów pól tekstowych: pól tekstowych opartych na stanie i pól tekstowych opartych na wartości. Wybierz typ, dla którego chcesz wyświetlać treści:

Zalecamy używanie pól tekstowych opartych na stanie, ponieważ zapewniają one bardziej kompletne i niezawodne podejście do zarządzania stanem elementu TextField. W tabeli poniżej znajdziesz różnice między tymi rodzajami pól tekstowych oraz główne zalety pól tekstowych opartych na stanie:

Na tej stronie dowiesz się, jak zaimplementować TextField, określić styl TextField danych wejściowych i skonfigurować inne TextField opcje, takie jak opcje klawiatury i wizualne przekształcanie danych wejściowych użytkownika.

Wybierz implementację TextField

Istnieją 2 poziomy wdrożenia TextField:

1. TextField to implementacja Material Design. Zalecamy wybranie tej implementacji, ponieważ jest ona zgodna z wytycznymi Material Design:
   • Domyślny styl to wypełniony.
   • OutlinedTextField to wersja stylu z konturem.
2. BasicTextField umożliwia użytkownikom edytowanie tekstu za pomocą klawiatury sprzętowej lub programowej, ale nie zawiera żadnych dekoracji, takich jak podpowiedź czy symbol zastępczy.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

Styl TextField

TextField i BasicTextField mają wiele wspólnych parametrów, które można dostosowywać. Pełna lista dla TextField jest dostępna w TextFieldkodzie źródłowym. Oto niepełna lista przydatnych parametrów:

• textStyle
• lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)
StateBasedText.kt

Jeśli projekt wymaga użycia elementu Material TextField lub OutlinedTextField, zalecamy użycie elementu TextField zamiast BasicTextField. Jednak BasicTextField należy używać podczas tworzenia projektów, które nie wymagają dekoracji z specyfikacji Material.

Stylizowanie danych wejściowych za pomocą interfejsu Brush API

Aby uzyskać bardziej zaawansowane style w TextField, możesz użyć interfejsu Brush API. W sekcji poniżej opisujemy, jak za pomocą pędzla dodać kolorowy gradient do pola TextField.

Więcej informacji o używaniu interfejsu Brush API do stylizowania tekstu znajdziesz w artykule Włączanie zaawansowanego stylizowania za pomocą interfejsu Brush API.

Wdrażanie gradientów kolorów za pomocą TextStyle

Aby podczas pisania w TextField zastosować gradient kolorów, ustaw wybrany pędzel jako TextStyle dla TextField. W tym przykładzie używamy wbudowanego pędzla z linearGradient, aby wyświetlić efekt gradientu tęczy podczas wpisywania tekstu w TextField.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)
StateBasedText.kt

Zarządzanie stanem pola tekstowego

TextField używa specjalnej klasy przechowującej stan o nazwie TextFieldState, która zawiera treść i bieżący wybór. TextFieldState można umieścić w dowolnym miejscu w architekturze. TextFieldState udostępnia 2 główne właściwości:

• initialText: zawartość TextField.
• initialSelection: wskazuje, gdzie obecnie znajduje się kursor lub zaznaczenie.

TextFieldState różni się od innych metod, takich jak wywołanie zwrotne onValueChange, tym, że TextFieldState w pełni obejmuje cały przepływ danych wejściowych. Obejmuje to używanie prawidłowych struktur danych pomocniczych, wstawianie filtrów i formatujących oraz synchronizowanie wszystkich zmian pochodzących z różnych źródeł.

Za pomocą TextFieldState() możesz przenieść stan w TextField. W tym celu zalecamy użycie funkcji rememberTextFieldState(). rememberTextFieldState() tworzy instancję TextFieldState w kompozycji, zapewnia zapamiętanie obiektu stanu oraz udostępnia wbudowane funkcje zapisywania i przywracania:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)
StateBasedText.kt

rememberTextFieldState może mieć pusty parametr lub wartość początkową przekazaną do reprezentowania wartości tekstu podczas inicjowania. Jeśli w kolejnej rekompozycji zostanie przekazana inna wartość, stan nie zostanie zaktualizowany. Aby zaktualizować stan po jego zainicjowaniu, wywołaj metody edycji na obiekcie TextFieldState.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)
StateBasedText.kt

Modyfikowanie tekstu za pomocą TextFieldBuffer

Element TextFieldBuffer służy jako kontener tekstu z możliwością edytowania, podobnie jak element StringBuilder. Zawiera zarówno treść tekstową, jak i informacje o bieżącym zaznaczeniu.

TextFieldBuffer często występuje jako zakres odbiorcy w funkcjach takich jak TextFieldState.edit, InputTransformation.transformInput lub OutputTransformation.transformOutput. W tych funkcjach możesz w razie potrzeby odczytywać lub aktualizować TextFieldBuffer. Następnie zmiany te są zatwierdzane w przypadku TextFieldState lub przekazywane do potoku renderowania w przypadku OutputTransformation.

Do modyfikowania zawartości bufora możesz używać standardowych funkcji edycji, takich jak append, insert, replace lub delete. Aby zmienić stan zaznaczenia, możesz bezpośrednio ustawić zmienną selection: TextRange lub użyć funkcji narzędziowych, takich jak placeCursorAtEnd lub selectAll. Sam wybór jest reprezentowany przez znak TextRange, gdzie indeks początkowy jest traktowany włącznie, a indeks końcowy wyłącznie. Znak TextRange z identycznymi wartościami początkową i końcową, np. (3, 3), oznacza pozycję kursora, w której nie są obecnie zaznaczone żadne znaki.

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        if (asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

Edytowanie tekstu w TextFieldState

Stan można edytować bezpośrednio za pomocą zmiennej stanu na kilka sposobów:

• edit: umożliwia edytowanie zawartości stanu i udostępnia funkcje TextFieldBuffer, dzięki czemu możesz używać metod takich jak insert, replace, append i innych.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd: czyści bieżący tekst, zastępuje go podanym tekstem i ustawia kursor na końcu.

  usernameState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText: usuwa cały tekst.

  usernameState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

Więcej informacji o innych funkcjach TextFieldState znajdziesz w TextFieldState dokumentacji.

Modyfikowanie danych wejściowych użytkownika

W sekcjach poniżej opisujemy, jak modyfikować dane wejściowe użytkownika. Przekształcanie danych wejściowych umożliwia filtrowanie TextField danych wejściowych podczas pisania przez użytkownika, a przekształcanie danych wyjściowych formatuje dane wejściowe użytkownika przed wyświetleniem ich na ekranie.

Filtrowanie danych wejściowych użytkownika za pomocą przekształceń danych wejściowych

Przekształcenie danych wejściowych umożliwia filtrowanie danych wejściowych od użytkownika. Jeśli np. TextField przyjmuje amerykański numer telefonu, chcesz akceptować tylko 10 cyfr. Wyniki InputTransformation są zapisywane w TextFieldState.

Dostępne są wbudowane filtry do typowych InputTransformation przypadków użycia. Aby ograniczyć długość, zadzwoń pod numer InputTransformation.maxLength():

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

Przekształcenia danych wejściowych

InputTransformation to interfejs z jedną funkcją. Podczas wdrażania niestandardowego InputTransformation musisz zastąpić TextFieldBuffer.transformInput:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

W przypadku numeru telefonu dodaj niestandardową transformację danych wejściowych, która zezwala na wpisywanie w polu TextField tylko cyfr:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!TextUtils.isDigitsOnly(asCharSequence())) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

Łączenie transformacji danych wejściowych

Aby dodać wiele filtrów do danych wejściowych, połącz je za pomocą funkcji rozszerzenia then.InputTransformation Filtry są wykonywane po kolei. Zalecamy najpierw stosować filtry o największej selektywności, aby uniknąć niepotrzebnych przekształceń danych, które ostatecznie zostaną odfiltrowane.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

Po dodaniu przekształceń danych wejściowych pole TextField może zawierać maksymalnie 10 cyfr.

Formatowanie danych wejściowych przed wyświetleniem

OutputTransformationumożliwiają formatowanie danych wprowadzanych przez użytkownika przed ich wyświetleniem na ekranie. W przeciwieństwie do InputTransformation formatowanie wykonane za pomocą OutputTransformation nie jest zapisywane w TextFieldState. Korzystając z poprzedniego przykładu numeru telefonu, musisz dodać nawiasy i myślniki w odpowiednich miejscach:

Jest to zaktualizowany sposób obsługi VisualTransformation w przypadku TextField opartych na wartościach. Kluczową różnicą jest to, że nie musisz obliczać mapowań przesunięć.

OutputTransformation to interfejs z jedną metodą abstrakcyjną. Aby wdrożyć niestandardową funkcję OutputTransformation, musisz zastąpić metodę transformOutput:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}
StateBasedText.kt

Aby sformatować numer telefonu, dodaj nawias otwierający na pozycji 0, nawias zamykający na pozycji 4 i myślnik na pozycji 8 do OutputTransformation:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}
StateBasedText.kt

Następnie dodaj OutputTransformation do TextField:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

Jak działają przekształcenia

Poniższy diagram przedstawia przepływ od wprowadzania tekstu do przekształcenia i wygenerowania danych wyjściowych:

1. Dane wejściowe są odbierane ze źródła sygnału.
2. Dane wejściowe są filtrowane za pomocą InputTransformation, który jest zapisywany w TextFieldState.
3. Dane wejściowe są przekazywane przez funkcję OutputTransformation w celu sformatowania.
4. Dane wejściowe są prezentowane w TextField.

Ustawianie opcji klawiatury

TextField umożliwia ustawienie opcji konfiguracji klawiatury, takich jak układ klawiatury, lub włączenie autokorekty, jeśli jest obsługiwana przez klawiaturę. Niektóre opcje mogą nie być gwarantowane, jeśli klawiatura programowa nie jest zgodna z opcjami podanymi tutaj. Oto lista obsługiwanych opcji klawiatury:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Dodatkowe materiały

• Automatyczne formatowanie numeru telefonu w polu tekstowym
• Wyświetlanie lub ukrywanie hasła na podstawie przełącznika użytkownika
• Sprawdzanie poprawności wpisywanych danych