Konfigurowanie pól tekstowych

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

TextField pozwala użytkownikom wpisywać i modyfikować tekst. Dostępne są 2 typy pól tekstowych: pola tekstowe zależne od stanu i pola tekstowe zależne od wartości. Wybierz typ treści, które chcesz wyświetlać:

Zalecamy używanie pól tekstowych zależnych od stanu, ponieważ zapewniają one bardziej kompletne i niezawodne podejście do zarządzania stanem TextField. W tabeli poniżej opisano różnice między tymi typami pól tekstowych oraz podano najważniejsze zalety pól tekstowych zależnych od stanu:

Na tej stronie opisano, jak zaimplementować TextField, stylizować dane wejściowe TextField i konfigurować inne opcje TextField, takie jak opcje klawiatury i wizualna zmiana danych wejściowych użytkownika.

Wybierz implementację TextField

Istnieją 2 poziomy wdrażania TextField:

1. TextField to implementacja Material Design. Zalecamy wybranie tej implementacji, ponieważ jest ona zgodna z wytycznymi dotyczącymi Material Design:
   • Styl domyślny to wypełniony.
   • OutlinedTextField to wersja stylizacji z konturem.
2. BasicTextField umożliwia użytkownikom edytowanie tekstu za pomocą klawiatury sprzętowej lub programowej, ale nie zawiera żadnych elementów dekoracyjnych, takich jak podpowiedź czy placeholder.

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 do dostosowywania. Pełna lista TextField jest dostępna w kodzie źródłowym TextField. 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 Twój projekt wymaga użycia materiału TextField lub OutlinedTextField, zalecamy użycie TextField zamiast BasicTextField. Jednak BasicTextField należy używać podczas tworzenia projektów, które nie wymagają dekoracji ze specyfikacji Material.

Konfigurowanie limitów linii

Komponenty TextField obsługują przewijanie wzdłuż jednej osi. Sposób przewijania jest określany przez parametr lineLimits. TextFields skonfigurowane do przewijania pojedynczej linii poziomo, a TextFields skonfigurowane do przewijania po wielu liniach pionowo.

Aby wybrać odpowiednią konfigurację linii dla TextField, użyj TextFieldLineLimits:

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

Konfiguracja SingleLine ma te cechy:

• Tekst nigdy nie jest przenoszony i nie pozwala na tworzenie nowych wierszy.
• Element TextField ma zawsze stałą wysokość.
• Jeśli tekst jest za długi, można go przewijać w poziomie.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)
StateBasedText.kt

Konfiguracja MultiLine ma te cechy:

• Akceptuje 2 parametry: minHeightInLines i maxHeightInLines.
• Pole tekstowe ma co najmniej minHeightInLines pikseli wysokości.
• Jeśli tekst się nie mieści, zostanie przeniesiony na kolejny wiersz.
• Jeśli tekst wymaga więcej wierszy, pole powiększa się, aż osiągnie wysokość maxHeightInLines, a następnie będzie można go przewijać w pionie.

Stylizowanie za pomocą interfejsu Brush API

Aby uzyskać bardziej zaawansowane efekty stylizacji w TextField, możesz użyć interfejsu Brush API. W tej sekcji opisaliśmy, jak za pomocą pędzla dodać kolorowy gradient do wejścia TextField.

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

Implementowanie kolorowych gradientów za pomocą TextStyle

Aby zastosować kolorowy gradient podczas pisania w polu TextField, ustaw wybrany przez siebie pędzel jako TextStyle dla pola 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 dedykowanej klasy TextFieldState do przechowywania treści i bieżącego wyboru. TextFieldState jest przeznaczony do podnoszenia w dowolnym miejscu w ramach Twojej architektury. TextFieldState udostępnia 2 główne właściwości:

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

Różnica między TextFieldState a innymi metodami, takimi jak onValueChange callback, polega na tym, że TextFieldState obejmuje cały przepływ danych wejściowych. Obejmuje to używanie prawidłowych struktur danych pomocniczych, wstawianie filtrów i formaterów, a także synchronizowanie wszystkich zmian pochodzących z różnych źródeł.

Możesz użyć elementu TextFieldState(), aby podać stan w elementach TextField. W tym celu zalecamy użycie funkcji rememberTextFieldState(). rememberTextFieldState() tworzy instancję TextFieldState w komponowalnym komponencie, zapewnia pamiętanie obiektu stanu i wbudowaną funkcję 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 przekazaną wartość początkową, która reprezentuje wartość tekstu podczas inicjalizacji. Jeśli w kolejnych składaniach zostanie przekazana inna wartość, wartość stanu nie zostanie zaktualizowana. Aby zaktualizować stan po jego zainicjowaniu, wywołaj metody edycji w obiekcie TextFieldState.

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

Modyfikowanie tekstu za pomocą TextFieldBuffer

Element TextFieldBuffer to edytowalny kontener tekstowy o funkcjonalności podobnej do elementu StringBuilder. Zawiera on zarówno treść tekstową, jak i informacje o bieżącym zaznaczeniu.

Często spotyka się TextFieldBuffer jako zakres odbiorczy w funkcjach takich jak TextFieldState.edit, InputTransformation.transformInput lub OutputTransformation.transformOutput. W tych funkcjach możesz odczytać lub zaktualizować zmienną TextFieldBuffer w razie potrzeby. Następnie te zmiany są zapisywane w TextFieldState lub przekazywane do ścieżki renderowania w przypadku OutputTransformation.

Zawartość bufora możesz modyfikować za pomocą standardowych funkcji edycji, takich jak append, insert, replace lub delete. Aby zmienić stan wyboru, ustaw bezpośrednio zmienną selection: TextRange lub użyj funkcji pomocniczych, takich jak placeCursorAtEnd lub selectAll. Samą selekcję reprezentuje elementTextRange, gdzie indeks początkowy jest traktowany włącznie, a indeks końcowy wyłącznie. TextRange z identycznymi wartościami początkową i końcową, np. (3, 3), oznacza pozycję kursora bez zaznaczonych znaków.

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

Edytuj tekst w aplikacji TextFieldState

Istnieje kilka metod, które umożliwiają edytowanie stanu bezpośrednio za pomocą zmiennej stanu:

• edit: umożliwia edytowanie zawartości stanu i uzyskiwanie dostępu do funkcji TextFieldBuffer, dzięki którym można 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: czyści cały tekst.

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

Inne funkcje TextFieldState znajdziesz w dokumentacji funkcji TextFieldState.

Modyfikowanie danych wejściowych użytkownika

W następnych sekcjach opisujemy, jak modyfikować dane wejściowe użytkownika. Przekształcenie danych wejściowych umożliwia filtrowanie danych wejściowych TextField w trakcie ich wpisywania przez użytkownika, a przekształcenie danych wyjściowych formatuje dane wejściowe przed ich wyświetleniem 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 na przykład TextField przyjmuje amerykański numer telefonu, możesz zaakceptować tylko 10 cyfr. Wyniki InputTransformation są zapisywane w pliku TextFieldState.

Do typowych zastosowań InputTransformation dostępne są wbudowane filtry. Aby ograniczyć długość, zadzwoń pod numer InputTransformation.maxLength():

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

Niestandardowe przekształcenia danych wejściowych

InputTransformation to interfejs jednej funkcji. Podczas implementowania 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 tylko cyfr w polu TextField:

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

Łańcuchowe transformacje danych wejściowych

Aby dodać do tekstu wiele filtrów, połącz InputTransformation za pomocą funkcji rozszerzenia then. Filtry są wykonywane kolejno. Zalecamy najpierw stosować najbardziej selektywne filtry, 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 dane wejściowe TextField mogą zawierać maksymalnie 10 cyfr.

Formatowanie danych wejściowych przed ich wyświetleniem

OutputTransformation umożliwiają formatowanie danych wejściowych użytkownika przed ich renderowaniem na ekranie. W przeciwieństwie do InputTransformation formatowanie wprowadzone za pomocą funkcji OutputTransformation nie jest zapisywane w TextFieldState. W przypadku poprzedniego przykładu numeru telefonu musisz w odpowiednich miejscach dodać nawiasy i kreski:

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

OutputTransformation to pojedynczy abstrakcyjny interfejs metody. Aby zaimplementować 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 w indeksie 0, nawias zamykający w indeksie 4 i kreskę w indeksie 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 danych od tekstu wejściowego do jego przekształcenia i wyjścia:

1. Dane wejściowe są otrzymywane ze źródła sygnału.
2. Dane wejściowe są filtrowane przez funkcję InputTransformation, która jest zapisywana w stanie TextFieldState.
3. Dane wejściowe są przekazywane przez OutputTransformation w celu sformatowania.
4. Dane wejściowe są wyświetlane w TextField.

Ustawianie opcji klawiatury

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

• capitalization
• autoCorrect
• keyboardType
• imeAction

Klasa KeyboardOptions zawiera teraz nowy parametr logiczny showKeyboardOnFocus, którego używasz w przypadku komponentów TextField zintegrowanych z TextFieldState. Ta opcja określa zachowanie klawiatury oprogramowania, gdy TextField nabiera fokusa za pomocą innych metod niż bezpośrednia interakcja użytkownika (na przykład programowo).

Gdy KeyboardOptions.showKeyboardOnFocus ma wartość Prawda, klawiatura programowa nie wyświetla się automatycznie, jeśli TextField uzyska fokus pośrednio. W takich przypadkach użytkownik musi wyraźnie kliknąć przycisk TextField, aby wyświetlić klawiaturę.

Definiowanie logiki interakcji z klawiaturą

Przycisk działania na klawiaturze programowej na Androidzie umożliwia interaktywne odpowiedzi w aplikacji. Więcej informacji o konfigurowaniu przycisku czynności znajdziesz w sekcji Ustawianie opcji klawiatury.

Aby określić, co się dzieje, gdy użytkownik kliknie ten przycisk działania, użyj parametru onKeyboardAction. Ten parametr może przyjmować opcjonalny interfejs funkcjonalny o nazwie KeyboardActionHandler. Interfejs KeyboardActionHandler zawiera jedną metodę onKeyboardAction(performDefaultAction: () -> Unit). Dzięki implementacji tej metody onKeyboardAction możesz wprowadzić logikę niestandardową, która będzie wykonywana, gdy użytkownik naciśnie przycisk akcji na klawiaturze.

Kilka standardowych typów działań klawiatury ma wbudowane domyślne zachowania. Na przykład wybranie ImeAction.Next lub ImeAction.Previous jako typu działania spowoduje przeniesienie zaznaczenia odpowiednio do następnego lub poprzedniego pola danych. Podobnie przycisk działania ustawiony na ImeAction.Done zazwyczaj zamyka klawiaturę programową. Te domyślne funkcje są wykonywane automatycznie i nie wymagają podania KeyboardActionHandler.

Oprócz tych domyślnych działań możesz też wdrożyć zachowanie niestandardowe. Gdy podasz obiekt KeyboardActionHandler, jego metoda onKeyboardAction otrzyma funkcję performDefaultAction. Funkcję performDefaultAction() możesz wywołać w dowolnym momencie w ramach logiki niestandardowej, aby wywołać standardowe domyślne działanie powiązane z bieżącą akcją IME.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)
StateBasedText.kt

Ten fragment kodu przedstawia typowy przypadek użycia na ekranie rejestracji z polem nazwy użytkownika. W tym polu wybrana jest opcja ImeAction.Next dla przycisku działania na klawiaturze. Dzięki temu możesz szybko i płynnie przejść do kolejnego pola hasła.

Oprócz standardowej nawigacji wymagane jest zainicjowanie procesu weryfikacji nazwy użytkownika w tle, gdy użytkownik wpisze hasło. Aby zachować domyślne zachowanie przełączania fokusa charakterystyczne dla funkcji ImeAction.Next, a zarazem zachować tę niestandardową logikę walidacji, wywoływana jest funkcja performDefaultAction(). Wywołanie funkcji performDefaultAction() implikuje uruchomienie leżącego u podstaw systemu zarządzania fokusem, aby przenieść fokus na następny odpowiedni element interfejsu, zachowując oczekiwany przepływ nawigacji.

Tworzenie bezpiecznego pola hasła

SecureTextField to komponent utworzony na podstawie pól tekstowych zależnych od stanu do zapisywania pól haseł. Zalecamy używanie znaku SecureTextField do tworzenia pól tekstowych haseł, ponieważ domyślnie ukrywa on wprowadzanie znaków i wyłącza działania wycinania i kopiowania.

SecureTextField ma textObfuscationMode, który określa, jak użytkownik widzi wprowadzanie znaków. textObfuscationMode ma te opcje:

• Hidden: ukrywa wszystkie dane wejściowe. Domyślne działanie na platformach komputerowych.

  

• Visible: wyświetla wszystkie dane wejściowe.

  

• RevealLastTyped: ukrywa wszystkie dane z wyjątkiem ostatniego znaku. Domyślne zachowanie na urządzeniach mobilnych.

  

Dodatkowe materiały

• Automatyczne formatowanie numeru telefonu w polu tekstowym
• Pokazywanie lub ukrywanie hasła na podstawie przełącznika użytkownika
• Weryfikowanie danych wejściowych podczas wpisywania przez użytkownika