Textfelder konfigurieren

Mit TextField können Nutzer Text eingeben und bearbeiten. Es gibt zwei Arten von Textfeldern: statusbasierte Textfelder und wertbasierte Textfelder. Wählen Sie den Typ aus, für den Inhalte angezeigt werden sollen:

Statusbasierte Textfelder Wertbasierte Textfelder

Wir empfehlen die Verwendung von statusbasierten Textfeldern, da sie einen umfassenderen und zuverlässigeren Ansatz für die Verwaltung des Status von TextField bieten. In der folgenden Tabelle werden die Unterschiede zwischen diesen Arten von Textfeldern beschrieben. Außerdem sind die wichtigsten Vorteile von statusbasierten Textfeldern aufgeführt:

Experimentell :Statusbasierte Textfelder basieren auf Material 3, Version 1.4.0-alpha14. Melden Sie alle Fehler in der Problemverfolgung.

Funktion	Wertbezogene Textfelder	Statusbasierte Textfelder	Vorteil auf Bundesstaatsebene
Zustandsverwaltung	Aktualisiert den Status des Textfelds mit dem onValueChange-Callback. Sie sind dafür verantwortlich, den value in Ihrem eigenen Status basierend auf den von onValueChange gemeldeten Änderungen zu aktualisieren.	Verwendet explizit ein TextFieldState-Objekt, um den Zustand der Texteingabe (Wert, Auswahl, Komposition) zu verwalten. Dieser Status kann gespeichert und geteilt werden.	Der onValueChange-Callback wurde entfernt, sodass Sie keine asynchronen Verhaltensweisen mehr einführen können. Der Status bleibt bei der Neuzusammensetzung, Konfiguration und beim Beenden des Prozesses erhalten.
Visuelle Transformation	Mit VisualTransformation wird die Darstellung des angezeigten Texts geändert. Normalerweise wird damit sowohl die Eingabe- als auch die Ausgabeformatierung in einem einzigen Schritt erledigt.	Verwendet InputTransformation zum Ändern der Eingabe des Nutzers, bevor sie im Status gespeichert wird, und OutputTransformation zum Formatieren von Textfeldinhalten, ohne die zugrunde liegenden Statusdaten zu ändern.	Sie müssen die Offsetzuordnung zwischen dem ursprünglichen Roh- und dem transformierten Text nicht mehr mit OutputTransformation angeben.
Zeilenlimits	Akzeptiert singleLine: Boolean, maxLines: Int und minLines: Int, um die Anzahl der Zeilen zu steuern.	Mit lineLimits: TextFieldLineLimits wird die minimale und maximale Anzahl von Zeilen konfiguriert, die das Textfeld einnehmen kann.	Beseitigt Unklarheiten bei der Konfiguration von Zeilenlimits durch Bereitstellung eines lineLimits-Parameters vom Typ TextFieldLineLimits.
Sicheres Textfeld	–	SecureTextField ist eine zusammensetzbare Funktion, die auf zustandsbasierten Textfeldern basiert und zum Schreiben eines Passwortfelds verwendet wird.	Ermöglicht die Optimierung der Sicherheit im Hintergrund und bietet eine vordefinierte Benutzeroberfläche mit textObfuscationMode.

Auf dieser Seite wird beschrieben, wie Sie TextField implementieren, die Eingabe von TextField gestalten und andere TextField-Optionen wie Tastaturoptionen konfigurieren und Nutzereingaben visuell transformieren.

TextField-Implementierung auswählen

Es gibt zwei Implementierungsebenen für TextField:

1. TextField ist die Material Design-Implementierung. Wir empfehlen Ihnen, diese Implementierung zu wählen, da sie den Material Design-Richtlinien entspricht:
   • Der Standardstil ist filled.
   • OutlinedTextField ist die umrissene Styling-Version.
2. Mit BasicTextField können Nutzer Text über eine Hardware- oder Softwaretastatur bearbeiten, es werden jedoch keine Dekorationen wie Hinweise oder Platzhalter angezeigt.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)
StateBasedText.kt

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)
StateBasedText.kt

Stil-TextField-

TextField und BasicTextField haben viele gemeinsame Parameter für die Anpassung. Die vollständige Liste für TextField ist im TextField-Quellcode verfügbar. Hier ist eine unvollständige Liste einiger nützlicher Parameter:

• textStyle
• lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)
StateBasedText.kt

Wir empfehlen TextField gegenüber BasicTextField, wenn Ihr Design ein Material TextField oder OutlinedTextField erfordert. BasicTextField sollte jedoch verwendet werden, wenn Designs erstellt werden, die keine Dekorationen aus der Material-Spezifikation benötigen.

Stileingabe mit der Brush API

Mit der Brush API können Sie TextField noch komplexer gestalten. Im folgenden Abschnitt wird beschrieben, wie Sie mit einem Pinsel einen farbigen Verlauf in die TextField-Eingabe einfügen.

Weitere Informationen zum Formatieren von Text mit der Brush API finden Sie unter Erweiterte Formatierung mit der Brush API aktivieren.

Farbverläufe mit TextStyle implementieren

Wenn Sie beim Tippen in einem 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 einem linearGradient, um den Regenbogenverlaufseffekt anzuzeigen, während Text in das TextField eingegeben wird.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)
StateBasedText.kt

Abbildung 1: Ein Regenbogen-Farbverlaufseffekt für TextField-Inhalte.

Status von Textfeldern verwalten

TextField verwendet für seinen Inhalt und die aktuelle Auswahl eine spezielle Status-Holder-Klasse namens TextFieldState. TextFieldState kann überall in Ihrer Architektur platziert werden. TextFieldState bietet zwei Haupteigenschaften:

• initialText: Inhalt des TextField.
• initialSelection: Gibt an, wo sich der Cursor oder die Auswahl gerade befindet.

TextFieldState unterscheidet sich von anderen Ansätzen wie dem onValueChange-Callback dadurch, dass TextFieldState den gesamten Eingabefluss vollständig kapselt. Dazu gehört die Verwendung der richtigen zugrunde liegenden Datenstrukturen, das Inlining von Filtern und Formatierungen sowie die Synchronisierung aller Änderungen aus verschiedenen Quellen.

Hinweis :Obwohl TextFieldState zum Compose Foundation-Modul gehört, hat es keine UI-Abhängigkeiten und ist als leistungsstarker State Holder konzipiert. TextFieldState verwendet nur Datenstrukturen, die vom Snapshot-System von Compose bereitgestellt werden. Es wird empfohlen, TextFieldState-Instanzen in Ihren ViewModels zu instanziieren und zu speichern.

Mit TextFieldState() können Sie den Status in TextField hochstufen. Wir empfehlen, dazu die Funktion rememberTextFieldState() zu verwenden. Mit rememberTextFieldState() wird die TextFieldState-Instanz in Ihrer Composable erstellt, das Statusobjekt wird gespeichert und es werden integrierte Funktionen zum Speichern und Wiederherstellen bereitgestellt:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)
StateBasedText.kt

rememberTextFieldState kann einen leeren Parameter oder einen übergebenen Startwert haben, um den Wert des Texts bei der Initialisierung darzustellen. Wenn bei einer nachfolgenden Neuzusammensetzung ein anderer Wert übergeben wird, wird der Wert des Status nicht aktualisiert. Wenn Sie den Status nach der Initialisierung aktualisieren möchten, rufen Sie Bearbeitungsmethoden für TextFieldState auf.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)
StateBasedText.kt

Abbildung 2: TextField mit „Nutzername“ als Ausgangstext.

Text mit TextFieldBuffer ändern

Ein TextFieldBuffer dient als bearbeitbarer Textcontainer, ähnlich wie ein StringBuilder. Es enthält sowohl den Textinhalt als auch Informationen zur aktuellen Auswahl.

TextFieldBuffer wird häufig als Empfängerbereich für Funktionen wie TextFieldState.edit, InputTransformation.transformInput oder OutputTransformation.transformOutput verwendet. In diesen Funktionen können Sie die TextFieldBuffer nach Bedarf lesen oder aktualisieren. Anschließend werden diese Änderungen entweder in TextFieldState übernommen oder im Fall von OutputTransformation an die Rendering-Pipeline weitergegeben.

Sie können Standardbearbeitungsfunktionen wie append, insert, replace oder delete verwenden, um den Inhalt des Puffers zu ändern. Wenn Sie den Auswahlstatus ändern möchten, legen Sie entweder die Variable selection: TextRange direkt fest oder verwenden Sie Hilfsfunktionen wie placeCursorAtEnd oder selectAll. Die Auswahl selbst wird durch ein TextRange dargestellt, wobei der Startindex inklusive und der Endindex exklusive ist. Ein TextRange mit identischen Start- und Endwerten, z. B. (3, 3), gibt eine Cursorposition an, bei der derzeit keine Zeichen ausgewählt sind.

val phoneNumberState = rememberTextFieldState()

LaunchedEffect(phoneNumberState) {
    phoneNumberState.edit { // TextFieldBuffer scope
        append("123456789")
    }
}

TextField(
    state = phoneNumberState,
    inputTransformation = InputTransformation { // TextFieldBuffer scope
        if (asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)
StateBasedText.kt

Text in TextFieldState bearbeiten

Es gibt mehrere Methoden, mit denen Sie den Status direkt über Ihre Statusvariable bearbeiten können:

• edit: Ermöglicht es Ihnen, den Statusinhalt zu bearbeiten, und bietet Ihnen TextFieldBuffer-Funktionen, damit Sie Methoden wie insert, replace und append verwenden können.

  val usernameState = rememberTextFieldState("I love Android")
  // textFieldState.text : I love Android
  // textFieldState.selection: TextRange(14, 14)
  usernameState.edit { insert(14, "!") }
  // textFieldState.text : I love Android!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { replace(7, 14, "Compose") }
  // textFieldState.text : I love Compose!
  // textFieldState.selection: TextRange(15, 15)
  usernameState.edit { append("!!!") }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(18, 18)
  usernameState.edit { selectAll() }
  // textFieldState.text : I love Compose!!!!
  // textFieldState.selection: TextRange(0, 18)
  StateBasedText.kt

• setTextAndPlaceCursorAtEnd: Löscht den aktuellen Text, ersetzt ihn durch den angegebenen Text und setzt den Cursor an das Ende.

  usernameState.setTextAndPlaceCursorAtEnd("I really love Android")
  // textFieldState.text : I really love Android
  // textFieldState.selection : TextRange(21, 21)
  StateBasedText.kt

• clearText: Löscht den gesamten Text.

  usernameState.clearText()
  // textFieldState.text :
  // textFieldState.selection : TextRange(0, 0)
  StateBasedText.kt

Informationen zu anderen TextFieldState-Funktionen finden Sie in der TextFieldState-Referenz.

Nutzereingabe ändern

In den folgenden Abschnitten wird beschrieben, wie Sie Nutzereingaben ändern. Mit der Eingabetransformation können Sie die TextField-Eingabe filtern, während der Nutzer tippt. Mit der Ausgabetransformation wird die Nutzereingabe formatiert, bevor sie auf dem Bildschirm angezeigt wird.

Nutzereingaben mit Eingabetransformationen filtern

Mit einer Eingabetransformation können Sie Eingaben des Nutzers filtern. Wenn Ihr TextField beispielsweise eine US-amerikanische Telefonnummer akzeptiert, möchten Sie nur 10 Ziffern zulassen. Die Ergebnisse von InputTransformation werden in TextFieldState gespeichert.

Hinweis: Ändern Sie den Status nicht im InputTransformation.transformInput()-Aufruf. Verwenden Sie stattdessen den Empfängerbereich TextFieldBuffer, um Text zu bearbeiten.

Es gibt integrierte Filter für häufige InputTransformation-Anwendungsfälle. Rufen Sie InputTransformation.maxLength() auf, um die Länge zu begrenzen:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)
StateBasedText.kt

Benutzerdefinierte Transformationen von Eingaben

InputTransformation ist eine Schnittstelle mit einer einzelnen Funktion. Wenn Sie Ihre benutzerdefinierte InputTransformation implementieren, müssen Sie TextFieldBuffer.transformInput überschreiben:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}
StateBasedText.kt

Fügen Sie für eine Telefonnummer eine benutzerdefinierte Eingabetransformation hinzu, die nur Ziffern in TextField zulässt:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!TextUtils.isDigitsOnly(asCharSequence())) {
            revertAllChanges()
        }
    }
}
StateBasedText.kt

Eingabetransformationen verketten

Wenn Sie Ihrer Texteingabe mehrere Filter hinzufügen möchten, können Sie InputTransformations mit der Erweiterungsfunktion then verketten. Filter werden nacheinander ausgeführt. Es empfiehlt sich, die selektivsten Filter zuerst anzuwenden, um unnötige Transformationen von Daten zu vermeiden, die letztendlich herausgefiltert werden.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)
StateBasedText.kt

Nachdem Sie Eingabetransformationen hinzugefügt haben, können Sie für die TextField-Eingabe maximal 10 Ziffern verwenden.

Eingabe vor der Anzeige formatieren

Mit OutputTransformation können Sie die Nutzereingabe formatieren, bevor sie auf dem Bildschirm gerendert wird. Im Gegensatz zu InputTransformation wird die Formatierung, die über OutputTransformation erfolgt, nicht in TextFieldState gespeichert. Wenn Sie auf dem vorherigen Beispiel für Telefonnummern aufbauen, müssen Sie an den entsprechenden Stellen Klammern und Bindestriche hinzufügen:

Abbildung 3: Eine US-amerikanische Telefonnummer mit korrekter Formatierung und entsprechenden Indexen.

Dies ist die aktualisierte Methode zum Verarbeiten von VisualTransformation in wertbasierten TextFields. Der Hauptunterschied besteht darin, dass Sie die Offsetzuordnungen nicht berechnen müssen.

OutputTransformation ist eine Schnittstelle mit einer einzelnen abstrakten Methode. Um eine benutzerdefinierte OutputTransformation zu implementieren, müssen Sie die Methode transformOutput überschreiben:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}
StateBasedText.kt

Wenn Sie eine Telefonnummer formatieren möchten, fügen Sie in OutputTransformation eine öffnende Klammer an Index 0, eine schließende Klammer an Index 4 und einen Bindestrich an Index 8 ein:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}
StateBasedText.kt

Fügen Sie als Nächstes OutputTransformation zu TextField hinzu:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)
StateBasedText.kt

Zusammenwirken von Transformationen

Das folgende Diagramm zeigt den Ablauf von der Texteingabe über die Transformation bis zur Ausgabe:

Abbildung 4. Ein Diagramm, das zeigt, wie Texteingaben Transformationen durchlaufen, bevor sie zu Textausgaben werden.

1. Eingabe wird von der Eingabequelle empfangen.
2. Die Eingabe wird durch ein InputTransformation gefiltert, das im TextFieldState gespeichert wird.
3. Die Eingabe wird zur Formatierung durch ein OutputTransformation geleitet.
4. Die Eingabe wird in TextField dargestellt.

Tastaturoptionen festlegen

Unter 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 angegebenen Optionen entspricht. Hier finden Sie eine Liste der unterstützten Tastaturoptionen:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Zusätzliche Ressourcen

• Telefonnummer in einem Textfeld automatisch formatieren
• Passwort basierend auf einer Nutzereinstellung ein- oder ausblenden
• Eingabe während der Eingabe durch den Nutzer validieren