Nutzereingaben verarbeiten

Mit TextField können Nutzer Text eingeben und ändern. Auf dieser Seite wird beschrieben, wie Sie TextField implementieren, die TextField-Eingabe formatieren und andere TextField-Optionen wie Tastaturoptionen und die visuelle Transformation von Nutzereingaben konfigurieren.

TextField-Implementierung auswählen

Es gibt zwei Ebenen der TextField-Implementierung:

1. TextField ist die Material Design-Implementierung. Wir empfehlen diese Implementierung, da sie den Material Design-Richtlinien entspricht:
   • Der Standardstil ist gefüllt.
   • OutlinedTextField ist die Version mit dem schlanken Design
2. Mit BasicTextField können Nutzer Text über eine Hardware- oder Softwaretastatur bearbeiten, es werden jedoch keine Verzierungen wie Hinweise oder Platzhalter angezeigt.

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}
TextSnippets.kt

Stil-TextField-

TextField und BasicTextField haben viele gemeinsame Parameter, mit denen sie angepasst werden können. Die vollständige Liste für TextField finden Sie im TextField-Quellcode. Im Folgenden finden Sie einige nützliche Parameter:

• singleLine
• maxLines
• textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}
TextSnippets.kt

Wir empfehlen TextField anstelle von BasicTextField, wenn Ihr Design ein Material vom Typ TextField oder OutlinedTextField erfordert. BasicTextField sollte jedoch verwendet werden, wenn Designs erstellt werden, für die die Verzierungen aus der Material-Spezifikation nicht erforderlich sind.

Stil für Eingaben mit der Brush API festlegen

Mit der Brush API kannst du erweiterte Stile in TextField nutzen. Im folgenden Abschnitt wird beschrieben, wie Sie mit einem Pinsel der Eingabe von TextField einen farbigen Farbverlauf hinzufügen.

Weitere Informationen zur Verwendung der Brush API zum Stilisieren von Text finden Sie unter Erweitertes Styling mit der Brush API aktivieren.

Farbige Farbverläufe mit TextStyle implementieren

Wenn Sie beim Eintippen in ein TextField einen Farbverlauf einfügen möchten, legen Sie den gewünschten Pinsel als TextStyle für das TextField fest. In diesem Beispiel verwenden wir einen integrierten Pinsel mit einer linearGradient, um den Regenbogen-Gradienteneffekt zu sehen, während Text in die TextField eingegeben wird.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

Tastaturoptionen festlegen

Über TextField können Sie Tastaturkonfigurationsoptionen wie das Tastaturlayout festlegen oder die Autokorrektur aktivieren, sofern sie von der Tastatur unterstützt wird. Einige Optionen sind möglicherweise nicht verfügbar, wenn die Softwaretastatur nicht den hier aufgeführten Optionen entspricht. Hier finden Sie eine Liste der unterstützten Tastaturoptionen.

• capitalization
• autoCorrect
• keyboardType
• imeAction

Eingabe formatieren

Mit TextField können Sie ein VisualTransformation für den Eingabewert festlegen. So können Sie z. B. Zeichen durch * für Passwörter ersetzen oder für Kreditkartennummern alle 4 Ziffern Bindestriche einfügen:

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}
TextSnippets.kt

Weitere Beispiele finden Sie im VisualTransformationSamples-Quellcode.

Eingabe bereinigen

Eine häufige Aufgabe beim Bearbeiten von Text besteht darin, führende Zeichen zu entfernen oder den Eingabestring bei jeder Änderung anderweitig zu transformieren.

Als Modell sollten Sie davon ausgehen, dass die Tastatur bei jedem onValueChange willkürliche und umfangreiche Änderungen vornehmen kann. Das kann beispielsweise passieren, wenn der Nutzer die automatische Korrektur verwendet, ein Wort durch ein Emoji ersetzt oder andere intelligente Bearbeitungsfunktionen nutzt. Um dies richtig zu handhaben, sollten Sie bei der Erstellung der Transformationslogik davon ausgehen, dass der aktuelle Text, der an onValueChange übergeben wird, keinen Bezug zu den vorherigen oder nächsten Werten hat, die an onValueChange übergeben werden.

Wenn Sie ein Textfeld implementieren möchten, in dem führende Nullen nicht zulässig sind, können Sie bei jeder Wertänderung alle führenden Nullen entfernen.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

Wenn Sie die Cursorposition beim Ausradieren von Text steuern möchten, verwenden Sie die Überladung TextFieldValue von TextField als Teil des Status.

Best Practices für Status

Im Folgenden finden Sie eine Reihe von Best Practices zum Definieren und Aktualisieren des TextField-Status, um Eingabeprobleme in Ihrer App zu vermeiden.

• MutableState für den Status TextField verwenden: Vermeiden Sie reaktive Streams wie StateFlow, um den Status TextField darzustellen, da diese Strukturen asynchrone Verzögerungen verursachen können.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• Verzögerungen beim Aktualisieren des Status vermeiden: Wenn Sie onValueChange aufrufen, aktualisieren Sie TextField synchron und sofort:

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}
TextSnippets.kt

• Ort der Statusdefinition: Wenn für den TextField-Status während der Eingabe Geschäftslogikvalidierungen erforderlich sind, ist es richtig, den Status in ViewModel zu setzen. Andernfalls können Sie als „Source of Truth“ Composables oder eine State-Holder-Klasse verwenden. Weitere Informationen darüber, wo dein Zustand angehoben werden soll, findest du in der Dokumentation zu Zustandswinden.