Gérer les entrées utilisateur

TextField permet aux utilisateurs de saisir et de modifier du texte. Cette page explique comment peut implémenter TextField, styliser l'entrée TextField et configurer d'autres options TextField, comme les options de clavier et les transformations visuelles les entrées utilisateur.

Choisissez l'implémentation de 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: <ph type="x-smartling-placeholder">
      </ph>
    • 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") }
    )
}

Champ de texte modifiable contenant le mot

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        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 de TextField est disponible dans la source TextField le 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)
    )
}

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 une Support TextField ou OutlineTextField. Cependant, BasicTextField doit être utilisé lors de la création de 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 appliquer un style au texte, consultez Activer les styles avancés avec l'API Brush

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 votre pinceau de votre choix en tant que TextStyle pour votre TextField. Dans cet exemple, nous utilisons pinceau intégré avec linearGradient pour afficher l'effet de dégradé arc-en-ciel 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)
)

Utiliser buildAnnotatedString et SpanStyle, avec linearGradient, pour ne personnaliser qu&#39;un texte.
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 claviers compatibles options:

  • 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)
    )
}

Champ de saisie du mot de passe, avec le texte masqué

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' }
        }
    )
}

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

Voici une série de bonnes pratiques pour définir et mettre à jour les TextField pour éviter les problèmes de saisie dans votre application.

  • Utiliser MutableState pour représenter l'état TextField: évitez à l'aide de flux réactifs tels que StateFlow pour représenter TextField, car ces structures peuvent introduire des retards asynchrones.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}

  • É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) }
        /*...*/
    )
}

  • 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.