Gérer les entrées utilisateur

TextField permet aux utilisateurs de saisir et de modifier du texte. Cette page explique comment implémenter TextField, appliquer un style à l'entrée TextField et configurer d'autres options TextField, telles que les options du clavier et la transformation visuelle des entrées utilisateur.

Choisir l'implémentation de TextField

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

1. TextField est l'implémentation Material Design. Nous vous recommandons de choisir cette implémentation, 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é.

@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

Style TextField

TextField et BasicTextField partagent de nombreux paramètres communs pour leur personnalisation. La liste complète de TextField est disponible dans le code source TextField. Voici une liste de quelques paramètres utiles :

• 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

Nous vous recommandons d'utiliser TextField plutôt que BasicTextField lorsque votre conception appelle un TextField ou un OutlineTextField Material. Toutefois, BasicTextField doit être utilisé lorsque vous créez des conceptions qui n'ont pas besoin des décorations de la spécification Material.

Appliquer un style à la saisie 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é coloré à l'entrée TextField.

Pour en savoir plus sur l'utilisation de l'API Brush pour appliquer un style au texte, consultez la section Activer les styles avancés avec l'API Brush.

Attention :L'utilisation actuelle de l'API Brush dans TextStyle est expérimentale. Les API expérimentales peuvent changer à l'avenir.

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

Pour implémenter un dégradé coloré lorsque vous saisissez du texte dans une 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 à mesure que du texte est saisi dans TextField.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)
TextSnippets.kt

Remarque :Veillez à utiliser la fonction remember pour conserver le pinceau lors des recompositions, lorsque l'état TextField change à chaque nouveau caractère saisi.

Figure 3. Utilisation de buildAnnotatedString et SpanStyle, avec linearGradient, pour personnaliser uniquement un texte.

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

Mettre en forme la saisie

TextField vous permet de définir un élément VisualTransformation au niveau de la valeur d'entrée. Par exemple, vous pouvez remplacer les caractères par * pour les mots de passe ou insérer des traits d'union tous les 4 chiffres dans le cas d'un numéro de carte de paiement :

@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

D'autres exemples sont disponibles dans le code source de VisualTransformationSamples.

Effacer l'entrée

Une tâche courante lors de la modification de texte consiste à supprimer les caractères de début ou à transformer la chaîne d'entrée chaque fois qu'elle change.

Partez du principe que le clavier peut apporter des modifications arbitraires et importantes à chaque onValueChange. Cela peut se produire, par exemple, si l'utilisateur a recours à la correction automatique, remplace un mot par un emoji ou exploite d'autres fonctionnalités de retouche intelligentes. Pour gérer ce comportement correctement, écrivez une logique de transformation selon laquelle le texte actuel transmis à onValueChange n'a aucun rapport avec les valeurs précédentes ou suivantes transmises à onValueChange.

Pour implémenter un champ de texte qui empêche les zéros au début, vous pouvez implémenter la suppression de tous les zéros au début d'une chaîne à chaque changement de valeur.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}
TextSnippets.kt

Pour contrôler la position du curseur lors du nettoyage du texte, utilisez la surcharge TextFieldValue de TextField dans le cadre de l'état.

Bonnes pratiques avec l'état

Vous trouverez ci-dessous une série de bonnes pratiques pour définir et mettre à jour l'état TextField afin d'éviter les problèmes de saisie dans votre application.

• Utilisez MutableState pour représenter l'état TextField: évitez d'utiliser des flux réactifs comme StateFlow pour représenter l'état TextField, car ces structures peuvent introduire des retards asynchrones.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• Évitez les retards de mise à jour de l'état: lorsque vous appelez onValueChange, mettez à jour votre TextField de manière synchrone et immédiate:

// 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

• Où définir l'état ? Si votre état TextField nécessite des validations de logique métier lors de la saisie, il est correct de hisser l'état dans votre ViewModel. Si ce n'est pas le cas, vous pouvez utiliser des composables ou une classe de conteneur d'état comme source de référence. Pour savoir où hisser votre état, consultez la documentation sur le hissage d'état.

Remarque :Pour en savoir plus sur ces bonnes pratiques, consultez l'article de blog Gestion de l'état efficace pour TextField dans Compose.