Gérer les entrées utilisateur

TextField permet aux utilisateurs de saisir et de modifier du texte. Cette page explique comment implémenter TextField, styliser l'entrée TextField et configurer d'autres options TextField, comme 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. Nous vous conseillons de choisir cette implémentation, comme suit : Material Design consignes:
   • 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 de matériel ou de logiciels clavier, 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 la source TextField code. 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 nécessite un Support 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.

Appliquer un style à la saisie avec l'API Brush

Vous pouvez utiliser l'API Brush pour appliquer un style plus avancé à votre TextField. La La section suivante explique comment ajouter un dégradé coloré à l'aide d'un pinceau. sur 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.

Attention :L'utilisation actuelle de l'API Brush dans TextStyle est expérimentale. Les API expérimentales sont susceptibles d'être modifiées à l'avenir.

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.

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 les 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 d'entrée dans votre application.

• Utilisez MutableState pour représenter l'état TextField : évitez d'utiliser des flux réactifs tels que StateFlow pour représenter l'état TextField, car ces structures peuvent entraîner 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) impose que l'établissement validations logiques à mesure que vous tapez, vous pouvez 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 la source de vérité. Pour savoir où hisser votre état, consultez la hissage d'état.

Remarque : Pour en savoir plus sur ces bonnes pratiques, consultez l'article de blog Gérer efficacement l'état de TextField dans Compose.