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 le 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 décrit les différences entre ces types de champs de texte et présente les principaux avantages des champs de texte basés sur l'état :

Fonctionnalité

Champs de texte basés sur des valeurs

Champs de texte basés sur l'état

Avantage basé sur l'état

Gestion de l'état

Mettez à jour l'état du champ de texte avec le rappel onValueChange. Vous devez mettre à jour 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 et 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'apparence du texte affiché. Cela gère généralement la mise en forme des entrées et des sorties en une seule étape.

Utilise InputTransformation pour modifier l'entrée 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.
  • Supprime l'ambiguïté lors de la configuration des limites de lignes 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.
  • Permet d'optimiser la sécurité en arrière-plan et inclut une UI prédéfinie avec textObfuscationMode.

Cette page explique comment implémenter TextField, appliquer un style à 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") }
)

Champ de texte modifiable contenant le mot 

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

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

Style TextField

TextField et BasicTextField partagent de nombreux paramètres communs pour leur 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)
)

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.

Styliser l'entrée avec l'API Brush

Vous pouvez utiliser l'API Brush pour appliquer un style plus avancé à votre TextField. La section suivante explique comment utiliser un pinceau pour ajouter un dégradé de couleur à une entrée TextField.

Pour en savoir plus sur l'utilisation de l'API Brush pour appliquer un style au texte, consultez 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)
)

Texte en cours de saisie dans un champ de texte, affichant un effet de dégradé arc-en-ciel.
Figure 1. Un effet de dégradé arc-en-ciel pour les contenus TextField.

Gérer l'état d'un champ de texte

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

  • initialText : contenu du TextField.
  • initialSelection : indique où se trouve le curseur ou la sélection.

Ce qui différencie TextFieldState des autres approches, comme le rappel onValueChange, c'est que TextFieldState encapsule entièrement l'intégralité du flux d'entrée. Cela inclut l'utilisation des structures de données de sauvegarde appropriées, l'intégration des filtres et des formateurs, 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é intégrée d'enregistrement et de restauration :

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

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,
)

Un TextField avec le texte "Username" (Nom d'utilisateur) apparaissant dans le champ de texte.
Figure 2. TextField avec "Username" comme texte initial.

Modifier le texte avec TextFieldBuffer

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

Vous rencontrez souvent TextFieldBuffer en tant que 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 mettre à jour 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 la 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'index de début est inclusif et l'index de fin est exclusif. Un TextRange dont les valeurs de début et de fin sont identiques, comme (3, 3), indique une position du curseur sans caractères sélectionnés.

val phoneNumberState = rememberTextFieldState("1234567890")

TextField(
    state = phoneNumberState,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Phone
    ),
    inputTransformation = InputTransformation.maxLength(10).then {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)

Modifier le texte dans TextFieldState

Plusieurs méthodes 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 pour que vous puissiez utiliser des méthodes telles que insert, replace, append, etc.

    // Initial textFieldState text passed in is "I love Android"
// textFieldState.text : I love Android
// textFieldState.selection: TextRange(14, 14)
textFieldState.edit { insert(14, "!") }
// textFieldState.text : I love Android!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { replace(7, 14, "Compose") }
// textFieldState.text : I love Compose!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { append("!!!") }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(18, 18)
textFieldState.edit { selectAll() }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(0, 18)

  • setTextAndPlaceCursorAtEnd : efface le texte actuel, le remplace par le texte donné et place le curseur à la fin.

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

  • clearText : efface tout le texte.

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

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 décrivent comment modifier les entrées 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 formate l'entrée utilisateur avant qu'elle ne s'affiche à l'écran.

Filtrer les entrées utilisateur avec des 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.

Il existe des filtres intégrés 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)
)

Transformations d'entrée personnalisées

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

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

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 (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}

Chaîner des transformations d'entrée

Pour ajouter plusieurs filtres à votre saisie de texte, associez des InputTransformation à l'aide de la fonction d'extension then. Les filtres sont exécutés de manière séquentielle. Il est recommandé d'appliquer d'abord les filtres les plus sélectifs pour éviter les transformations inutiles sur les données qui seraient finalement filtrées.

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

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

Mettre en forme l'entrée avant qu'elle ne s'affiche

Les OutputTransformation vous permettent de mettre en forme les entrées utilisateur avant qu'elles ne s'affichent à l'écran. Contrairement à InputTransformation, la mise en forme effectuée via OutputTransformation n'est pas enregistrée dans TextFieldState. En reprenant 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 :

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

Il s'agit de la nouvelle méthode de gestion des VisualTransformation dans les TextField basés sur des valeurs. La principale différence est que vous n'avez pas besoin de calculer leurs mappages de décalage.

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

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

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 de votre OutputTransformation :

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

Ensuite, ajoutez votre OutputTransformation à TextField :

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)

Fonctionnement combiné des transformations

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

Visualisation de la façon dont une entrée de texte est transformée avant de devenir une sortie de texte.
Figure 4. Diagramme montrant comment une entrée textuelle subit des transformations avant de devenir une sortie textuelle.
  1. L'entrée est reçue de la source d'entrée.
  2. L'entrée est filtrée via un InputTransformation, qui est enregistré dans le TextFieldState.
  3. L'entrée est transmise via un OutputTransformation pour la mise en forme.
  4. L'entrée est présentée dans le TextField.

Définir les options du 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