Nutzereingaben verarbeiten

In 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 der/die/das Gliederung Stilversion
2. Mit BasicTextField können Nutzer Text über Hard- oder Software bearbeiten Tastatur, aber bietet 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

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

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

Stil-TextField-

Für TextField und BasicTextField gibt es viele gemeinsame Parameter zur Anpassung. . Die vollständige Liste für TextField ist in der TextField-Quelle verfügbar Code hinzu. 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 über BasicTextField, wenn Ihr Design einen Material TextField oder OutlinedTextField. BasicTextField sollte jedoch verwendet werden, wenn Sie Designs erstellen, 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. Die Im folgenden Abschnitt wird beschrieben, wie Sie mit einem Pinsel einen farbigen Farbverlauf hinzufügen können. bis TextField-Eingabe.

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

Achtung: Die aktuelle Nutzung der Brush API in TextStyle ist experimentell. Experimentelle APIs können sich in Zukunft ändern.

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

Hinweis: Verwenden Sie die Funktion remember, um den Pinsel bei Neuzusammensetzungen beizubehalten, wenn sich der Status TextField bei jedem neu eingegebenen Zeichen ändert.

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

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 können möglicherweise nicht garantiert werden, wenn die Softwaretastatur nicht den Optionen, die hier zur Verfügung stehen. Hier ist die Liste der unterstützten Tastaturen Optionen:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Eingabe formatieren

Mit TextField können Sie Folgendes festlegen: VisualTransformation auf den Eingabewert, z. B. Ersetzen Sie Zeichen durch * für Passwörter oder Einsetzen von Bindestrichen alle 4 Ziffern für eine Kreditkartennummer:

@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 gängige Aufgabe bei der Textbearbeitung ist das Entfernen von führenden Zeichen oder den Eingabestring bei jeder Änderung transformieren.

Als Modell sollten Sie davon ausgehen, dass die Tastatur willkürlich und groß bearbeitet jeden onValueChange. Das kann zum Beispiel passieren, wenn Nutzende Autokorrektur, das Ersetzen von Wörtern durch ein Emoji oder andere intelligente Bearbeitungsfunktionen. Bis richtig verarbeitet, jede Transformationslogik in der Annahme, dass Der aktuelle an onValueChange übergebene Text steht in keinem Zusammenhang mit dem vorherigen oder nächsten -Werte, 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

Um die Cursorposition beim Bereinigen von Text zu steuern, verwenden Sie den TextFieldValue Überlastung von TextField als Teil des Bundesstaates.

Best Practices mit Status

Im Folgenden finden Sie eine Reihe von Best Practices zum Definieren und Aktualisieren von TextField um Eingabeprobleme in der App zu vermeiden.

• Verwenden Sie MutableState, um den Status TextField darzustellen: Vermeiden Sie mit reaktiven Streams wie StateFlow, um TextField, da diese Strukturen asynchrone Verzögerungen verursachen 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

• Definition: Wenn in Ihrem TextField-Bundesstaat Unternehmen Logikvalidierungen während der Eingabe geben, ist es richtig, den Zustand auf Ihre ViewModel. Andernfalls können Sie Composables oder eine Stateholder-Klasse als „Source of Truth“ verwenden. Weitere Informationen dazu, wo Sie den Status hochladen sollten, finden Sie in der Dokumentation zum Hochladen von Status.

Hinweis: Weitere Informationen zu diesen Best Practices finden Sie in der Effektive Statusverwaltung für TextField im Blogpost „Compose“