Nutzereingaben verarbeiten

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

TextField-Implementierung auswählen

Es gibt zwei Ebenen der TextField-Implementierung:

1. TextField ist die Material Design-Implementierung. Wir empfehlen, diese Implementierung zu wählen, da sie den Material Design-Richtlinien entspricht:
   • Der Standardstil ist gefüllt.
   • OutlinedTextField ist die Stilversion für Outline.
2. Mit BasicTextField können Nutzer Text über die Hardware- oder Softwaretastatur bearbeiten, jedoch keine Hinweise oder Platzhalter.

@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 nutzen viele gemeinsame Parameter, um sie anzupassen. Die vollständige Liste für TextField finden Sie im TextField-Quellcode. Im Folgenden finden Sie eine unvollstä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

Wir empfehlen TextField gegenüber BasicTextField, wenn Ihr Design ein Material-TextField- oder OutlineTextField-Element erfordert. BasicTextField sollte jedoch für Designs verwendet werden, die die Dekorationen aus der Materialspezifikation nicht benötigen.

Eingabe mit der Brush API gestalten

Mit der Brush API kannst du erweiterte Stile in TextField nutzen. Im folgenden Abschnitt wird beschrieben, wie Sie einen Pinsel verwenden können, um der TextField-Eingabe einen farbigen Farbverlauf hinzuzufügen.

Weitere Informationen zur Verwendung der Brush API zum Gestalten von Text finden Sie unter Erweiterte Stile mit der Brush API aktivieren.

Farbverläufe mit TextStyle implementieren

Wenn Sie bei der Eingabe in TextField einen Farbverlauf implementieren möchten, legen Sie den Pinsel Ihrer Wahl als TextStyle für TextField fest. In diesem Beispiel verwenden wir einen integrierten Pinsel mit einem linearGradient, um den Regenbogen-Farbverlaufseffekt anzuzeigen, sobald 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

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 sind möglicherweise nicht garantiert, wenn die Softwaretastatur nicht den hier bereitgestellten Optionen entspricht. 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 findest du 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 für jeden onValueChange beliebige und große Bearbeitungen vornehmen kann. Das kann beispielsweise der Fall sein, wenn der Nutzer die Autokorrektur verwendet, ein Wort durch ein Emoji ersetzt oder andere intelligente Bearbeitungsfunktionen verwendet. Damit dies korrekt verarbeitet wird, schreiben Sie jede Transformationslogik unter der Annahme, dass der aktuelle an onValueChange übergebene Text nicht mit den vorherigen oder nächsten Werten steht, die an onValueChange übergeben werden.

Um ein Textfeld zu implementieren, das keine führenden Nullen zulässt, können Sie alle führenden Nullen bei jeder Wertänderung 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 Zustands, um die Cursorposition beim Bereinigen von Text zu steuern.

Best Practices mit Status

Im Folgenden finden Sie eine Reihe von Best Practices zum Definieren und Aktualisieren des TextField-Status, um Eingabeprobleme in Ihrer Anwendung 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

• Definition der Statusangabe: Wenn für den Status TextField bei der Eingabe Geschäftslogikvalidierungen erforderlich sind, kann der Status auf ViewModel gezogen werden. Ist dies nicht der Fall, können Sie zusammensetzbare Funktionen oder eine State Holder-Klasse als Datenquelle verwenden. Weitere Informationen darüber, wo dein Zustand angehoben werden soll, findest du in der Dokumentation zu state Winden.

Empfehlungen für dich

• Hinweis: Der Linktext wird angezeigt, wenn JavaScript deaktiviert ist.
• Benutzeroberfläche für das Schreiben erstellen
• State und Jetpack Compose
• UI-Status in „Compose“ speichern