Nutzereingaben verarbeiten

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

TextField-Implementierung auswählen

Es gibt zwei Ebenen der TextField-Implementierung:

  1. TextField ist die Material Design-Implementierung. Wir empfehlen, diese Implementierung gemäß den Material Design-Richtlinien auszuwählen:
  2. Mit BasicTextField können Nutzer Text über eine Hardware- oder Softwaretastatur bearbeiten. Es bietet jedoch keine Elemente wie Hinweise oder Platzhalter.

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

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

Ein bearbeitbares Textfeld mit dem Wort 

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

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

Ein bearbeitbares Textfeld mit lila Rahmen und Label.

Stil-TextField-

Für TextField und BasicTextField gibt es viele gemeinsame Parameter, um sie anzupassen. Die vollständige Liste für TextField finden Sie im TextField-Quellcode. Dies ist eine nicht vollständige Liste einiger nützlicher 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

Ein mehrzeiliges TextField mit zwei bearbeitbaren Zeilen sowie dem Label

Wir empfehlen, TextField anstelle von BasicTextField zu verwenden, wenn für dein Design ein Material-TextField oder -OutlineTextField erforderlich ist. BasicTextField sollte jedoch bei der Erstellung von Designs verwendet werden, die die Dekoration aus der Material-Spezifikation nicht benötigen.

Stileingabe mit der Brush API

Sie können die Brush API für komplexere Stile in Ihrem TextField verwenden. Im folgenden Abschnitt wird beschrieben, wie Sie der TextField-Eingabe mit einem Pinsel einen Farbverlauf hinzufügen können.

Weitere Informationen dazu, wie Sie die Brush API zum Gestalten von Text verwenden, finden Sie unter Erweiterte Stile mit der Brush API aktivieren.

Farbverläufe mit TextStyle implementieren

Wenn Sie einen Farbverlauf während der Eingabe in einem TextField implementieren möchten, legen Sie den Pinsel Ihrer Wahl als TextStyle für TextField fest. In diesem Beispiel wird ein integrierter Pinsel mit einem linearGradient verwendet, um den Regenbogen-Farbverlaufseffekt zu sehen, während Text in 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

Verwenden Sie buildAnnotatedString und SpanStyle zusammen mit linearGradient, um nur einen Teil des Textes anzupassen.
Abbildung 3: Verwenden Sie buildAnnotatedString, SpanStyle und linearGradient, um nur einen Textabschnitt anzupassen.

Tastaturoptionen festlegen

Mit TextField können Sie Optionen für Tastaturkonfigurationen festlegen, z. B. das Tastaturlayout, oder die Autokorrektur aktivieren, wenn sie von der Tastatur unterstützt wird. Einige Optionen können möglicherweise nicht garantiert werden, wenn die Softwaretastatur nicht den hier angegebenen Optionen entspricht. Unterstützte Tastaturoptionen:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Eingabe formatieren

Mit TextField können Sie einen VisualTransformation für den Eingabewert festlegen. Beispielsweise können Sie Zeichen durch * für Passwörter ersetzen oder bei einer Kreditkartennummer alle vier 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

Ein Passwort-Texteingabefeld, in dem der Text maskiert ist

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 beliebige und umfangreiche Änderungen an jedem onValueChange vornehmen kann. Das kann beispielsweise vorkommen, wenn der Nutzer die Autokorrektur verwendet, ein Wort durch ein Emoji ersetzt oder andere intelligente Bearbeitungsfunktionen verwendet. Damit dies richtig funktioniert, schreiben Sie eine Transformationslogik unter der Annahme, dass der aktuell an onValueChange übergebene Text nicht mit den vorherigen oder nächsten Werten übereinstimmt, die an onValueChange übergeben werden.

Sie können ein Textfeld implementieren, das führende Nullen nicht zulässt, indem 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

Verwenden Sie die TextFieldValue-Überlastung von TextField als Teil des Status, um die Cursorposition beim Bereinigen von Text zu steuern.

Best Practices für Status

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

  • Verwenden Sie MutableState, um den TextField-Status darzustellen: Vermeiden Sie reaktive Streams wie StateFlow zur Darstellung des TextField-Status, da diese Strukturen zu asynchronen Verzögerungen führen 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

  • Wo wird der Status definiert? Wenn für den Bundesstaat TextField während der Eingabe eine Validierung der Geschäftslogik erforderlich ist, wird der Status korrekt in Ihre ViewModel gezogen. Ist dies nicht der Fall, können Sie zusammensetzbare Funktionen oder eine State-Holder-Klasse als „Source of Truth“ verwenden. Weitere Informationen dazu, wo Sie Ihren Bundesstaat hochziehen sollten, finden Sie in der Dokumentation zum Hebeziehen des Zustands.