Configurer les champs de texte

TextField permet aux utilisateurs de saisir et de modifier du texte. Vous pouvez utiliser deux types de champs de texte: les champs de texte basés sur l'état et les champs de texte basés sur la valeur. Sélectionnez le type pour lequel vous souhaitez afficher du contenu:

Nous vous recommandons d'utiliser des champs de texte basés sur l'état, car ils offrent une approche plus complète et plus fiable pour gérer l'état d'un TextField. Le tableau suivant présente les différences entre ces types de champs de texte et les principaux avantages des champs de texte basés sur l'état:

Fonctionnalité

Champs de texte basés sur la valeur

Champs de texte basés sur l'état

Avantages liés à l'état

Gestion de l'état

Met à jour l'état du champ de texte avec le rappel onValueChange. Vous êtes responsable de la mise à jour de value dans votre propre état en fonction des modifications signalées par onValueChange.

Utilise explicitement un objet TextFieldState pour gérer l'état de la saisie de texte (valeur, sélection, composition). Cet état peut être mémorisé et partagé.
  • Le rappel onValueChange a été supprimé, ce qui vous empêche d'introduire des comportements asynchrones.
  • L'état survit à la recomposition, à la configuration et à l'arrêt du processus.

Transformation visuelle

Utilise VisualTransformation pour modifier l'affichage du texte. Cela gère généralement la mise en forme des entrées et des sorties en une seule étape.

Utilise InputTransformation pour modifier la saisie de l'utilisateur avant qu'elle ne soit validée dans l'état, et OutputTransformation pour mettre en forme le contenu du champ de texte sans modifier les données d'état sous-jacentes.
  • Vous n'avez plus besoin de fournir le mappage de décalage entre le texte brut d'origine et le texte transformé avec OutputTransformation.

Limites de lignes

Accepte singleLine: Boolean, maxLines: Int et minLines: Int pour contrôler le nombre de lignes.

Utilise lineLimits: TextFieldLineLimits pour configurer le nombre minimal et maximal de lignes que le champ de texte peut occuper.
  • Élimine l'ambiguïté lors de la configuration des limites de ligne en fournissant un paramètre lineLimits de type TextFieldLineLimits.

Champ de texte sécurisé

N/A

SecureTextField est un composable basé sur des champs de texte basés sur l'état pour écrire un champ de mot de passe.
  • Vous permet d'optimiser la sécurité en arrière-plan et est fourni avec une UI prédéfinie avec textObfuscationMode.

Cette page explique comment implémenter TextField, styliser l'entrée TextField et configurer d'autres options TextField, telles que les options de clavier et la transformation visuelle de l'entrée utilisateur.

Choisir l'implémentation TextField

Il existe deux niveaux d'implémentation de TextField:

  1. TextField est l'implémentation Material Design. Il s'agit de celle que nous recommandons, car elle respecte les consignes Material Design :
    • Le style par défaut est rempli.
    • OutlinedTextField correspond à la version de style contour.
  2. BasicTextField permet aux utilisateurs de modifier du texte à l'aide du clavier physique ou virtuel, mais ne fournit aucune décoration comme un indice ou un espace réservé.

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

Champ de texte modifiable contenant le mot 

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

Champ de texte modifiable avec une bordure et un libellé violets

Style TextField

TextField et BasicTextField partagent de nombreux paramètres communs pour la personnalisation. La liste complète des éléments TextField est disponible dans le code source TextField. Voici une liste non exhaustive de quelques paramètres utiles:

  • 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

Champ de texte multiligne, avec deux lignes modifiables et le libellé

Nous vous recommandons d'utiliser TextField plutôt que BasicTextField lorsque votre conception nécessite un élément Material TextField ou OutlinedTextField. Toutefois, vous devez utiliser BasicTextField lorsque vous créez des conceptions qui n'ont pas besoin des décorations de la spécification Material.

Mettre en forme la saisie avec l'API Brush

Vous pouvez utiliser l'API Brush pour créer des styles plus avancés dans votre TextField. La section suivante explique comment utiliser un pinceau pour ajouter un dégradé de couleur à l'entrée TextField.

Pour en savoir plus sur l'utilisation de l'API Brush pour styliser le texte, consultez la section Activer le style avancé avec l'API Brush.

Implémenter des dégradés de couleurs à l'aide de TextStyle

Pour implémenter un dégradé de couleur lorsque vous saisissez du texte dans un TextField, définissez le pinceau de votre choix en tant que TextStyle pour votre TextField. Dans cet exemple, nous utilisons un pinceau intégré avec un linearGradient pour afficher l'effet de dégradé arc-en-ciel lorsque du texte est saisi dans le TextField.

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

Utilisation de buildAnnotatedString et de SpanStyle, ainsi que de linearGradient, pour ne personnaliser qu'un seul élément de texte.
Figure 1. Effet de dégradé arc-en-ciel pour le contenu TextField.

Gérer l'état du champ de texte

TextField utilise une classe de conteneur d'état dédiée appelée TextFieldState pour son contenu et sa sélection actuelle. TextFieldState est conçu pour être hissé partout où il s'intègre dans votre architecture. TextFieldState fournit deux propriétés principales:

  • initialText: contenu du TextField.
  • initialSelection: indique l'emplacement actuel du curseur ou de la sélection.

Ce qui différencie TextFieldState des autres approches, comme le rappel onValueChange, est que TextFieldState encapsule entièrement l'ensemble du flux d'entrée. Cela inclut l'utilisation des structures de données de support appropriées, l'intégration de filtres et de formatseurs, ainsi que la synchronisation de toutes les modifications provenant de différentes sources.

Vous pouvez utiliser TextFieldState() pour hisser l'état dans TextField. Pour ce faire, nous vous recommandons d'utiliser la fonction rememberTextFieldState(). rememberTextFieldState() crée l'instance TextFieldState dans votre composable, s'assure que l'objet d'état est mémorisé et fournit une fonctionnalité d'enregistrement et de restauration intégrée:

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

rememberTextFieldState peut avoir un paramètre vide ou une valeur initiale transmise pour représenter la valeur du texte lors de l'initialisation. Si une valeur différente est transmise lors d'une recomposition ultérieure, la valeur de l'état n'est pas mise à jour. Pour mettre à jour l'état après son initialisation, appelez les méthodes de modification sur TextFieldState.

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

TextField avec le texte "Nom d'utilisateur" dans le champ de texte.
Figure 2 TextField avec le texte initial "Nom d'utilisateur".

Modifier le texte avec TextFieldBuffer

Un TextFieldBuffer sert de conteneur de texte modifiable, semblable à un StringBuilder. Il contient à la fois le contenu textuel et des informations sur la sélection actuelle.

Vous rencontrez souvent TextFieldBuffer comme champ d'application du récepteur sur des fonctions telles que TextFieldState.edit, InputTransformation.transformInput ou OutputTransformation.transformOutput. Dans ces fonctions, vous pouvez lire ou modifier le TextFieldBuffer si nécessaire. Ensuite, ces modifications sont soit validées dans TextFieldState, soit transmises au pipeline de rendu dans le cas de OutputTransformation.

Vous pouvez utiliser des fonctions de modification standards telles que append, insert, replace ou delete pour modifier le contenu du tampon. Pour modifier l'état de sélection, définissez directement sa variable selection: TextRange ou utilisez des fonctions utilitaires telles que placeCursorAtEnd ou selectAll. La sélection elle-même est représentée par un TextRange, où l'indice de début est inclusif et l'indice de fin est exclusif. Un TextRange avec des valeurs de début et de fin identiques, comme (3, 3), indique une position du curseur sans caractère actuellement sélectionné.

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

Modifier le texte dans TextFieldState

Il existe plusieurs méthodes qui vous permettent de modifier l'état directement via votre variable d'état:

  • edit: vous permet de modifier le contenu de l'état et vous fournit des fonctions TextFieldBuffer afin que vous puissiez utiliser des méthodes telles que insert, replace, append, etc.

    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: efface le texte actuel, le remplace par le texte donné et définit le curseur à la fin.

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

  • clearText: efface tout le texte.

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

Pour en savoir plus sur les autres fonctions TextFieldState, consultez la documentation de référence sur TextFieldState.

Modifier l'entrée utilisateur

Les sections suivantes expliquent comment modifier la saisie utilisateur. La transformation d'entrée vous permet de filtrer l'entrée TextField pendant que l'utilisateur saisit du texte, tandis que la transformation de sortie met en forme l'entrée de l'utilisateur avant qu'elle ne s'affiche à l'écran.

Filtrer la saisie utilisateur à l'aide de transformations d'entrée

Une transformation d'entrée vous permet de filtrer les entrées de l'utilisateur. Par exemple, si votre TextField accepte un numéro de téléphone américain, vous ne souhaitez accepter que 10 chiffres. Les résultats de InputTransformation sont enregistrés dans TextFieldState.

Des filtres intégrés sont disponibles pour les cas d'utilisation courants de InputTransformation. Pour limiter la longueur, appelez InputTransformation.maxLength():

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

Transformations de saisie personnalisées

InputTransformation est une interface de fonction unique. Lorsque vous implémentez votre InputTransformation personnalisée, vous devez remplacer TextFieldBuffer.transformInput:

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

Pour un numéro de téléphone, ajoutez une transformation d'entrée personnalisée qui n'autorise que la saisie de chiffres dans le TextField:

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

Chaîner des transformations d'entrée

Pour ajouter plusieurs filtres à votre saisie de texte, enchaînez des InputTransformation à l'aide de la fonction d'extension then. Les filtres sont exécutés de manière séquentielle. Nous vous recommandons d'appliquer d'abord les filtres les plus sélectifs afin d'éviter les transformations inutiles sur les données qui seront finalement filtrées.

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

Après avoir ajouté des transformations d'entrée, l'entrée TextField accepte 10 chiffres maximum.

Mettre en forme les données avant leur affichage

Les OutputTransformation vous permettent de mettre en forme la saisie utilisateur avant qu'elle ne soit affichée à l'écran. Contrairement à InputTransformation, la mise en forme effectuée via OutputTransformation n'est pas enregistrée dans TextFieldState. En vous appuyant sur l'exemple de numéro de téléphone précédent, vous devez ajouter des parenthèses et des tirets aux endroits appropriés:

Numéro de téléphone américain, correctement formaté avec des parenthèses, des tirets et des indices correspondants.
Figure 3 Un numéro de téléphone américain au format approprié et avec les indices correspondants.

Il s'agit de la nouvelle méthode de gestion des VisualTransformation dans les TextField basées sur la valeur, avec une différence clé : vous n'avez pas à calculer leurs mappages de décalage.

OutputTransformation est une interface de méthode abstraite unique. Pour implémenter un OutputTransformation personnalisé, vous devez remplacer la méthode transformOutput:

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

Pour mettre en forme un numéro de téléphone, ajoutez une parenthèse ouvrante à l'index 0, une parenthèse fermante à l'index 4 et un tiret à l'index 8 à votre OutputTransformation:

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

Ajoutez ensuite votre OutputTransformation à TextField:

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

Fonctionnement des transformations

Le schéma suivant montre le flux de l'entrée de texte à la transformation en sortie:

Visualisation de la façon dont le texte saisi subit des transformations avant de devenir une sortie textuelle.
Figure 4. Schéma illustrant comment le texte saisi subit des transformations avant de devenir une sortie textuelle.
  1. La source d'entrée reçoit une entrée.
  2. L'entrée est filtrée via un InputTransformation, qui est enregistré dans TextFieldState.
  3. L'entrée est transmise via un OutputTransformation pour le formatage.
  4. L'entrée est présentée dans TextField.

Définir les options de clavier

TextField vous permet de définir des options de configuration du clavier, telles que la disposition des touches, ou d'activer la correction automatique si le clavier le permet. Certaines options ne sont pas garanties si le clavier logiciel ne respecte pas les options fournies ici. Voici la liste des options de clavier compatibles:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Ressources supplémentaires