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 filled (ausgefü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 können Sie Ihr TextField noch weiter anpassen. Im folgenden Abschnitt wird beschrieben, wie Sie mit einem Pinsel der Eingabe von TextField einen farbigen Farbverlauf hinzufügen.

Weitere Informationen zum Verwenden 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 eine VisualTransformation für den Eingabewert festlegen, z. B. Zeichen durch * für Passwörter ersetzen oder bei einer Kreditkartennummer alle vier Ziffern durch Bindestrich 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 bei der Textbearbeitung besteht darin, führende Zeichen zu entfernen oder den Eingabestring jedes Mal zu ändern, wenn er sich ändert.

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.

• Verwende MutableState, um den TextField-Status darzustellen: Verwende keine reaktiven Streams wie StateFlow, um den TextField-Status darzustellen, da diese Strukturen zu asynchronen Verzögerungen führen können.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• Vermeiden Sie Verzögerungen beim Aktualisieren des Status: 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 Composables oder eine State-Holder-Klasse als „Source of Truth“ verwenden. Weitere Informationen dazu, wo Sie den Status einbinden können, finden Sie in der Dokumentation zum Einbinden von Status.