Gestisci l'input utente

TextField consente agli utenti di inserire e modificare il testo. Questa pagina descrive come implementare TextField, impostare lo stile dell'input TextField e configurare altre opzioni TextField, come le opzioni della tastiera e la trasformazione visiva dell'input utente.

Scegli l'implementazione di TextField

Esistono due livelli di implementazione di TextField:

1. TextField è l'implementazione di Material Design. Ti consigliamo di scegliere questa implementazione in base al Material Design linee guida:
   • Lo stile predefinito è riempito
   • OutlinedTextField è il struttura versione per gli stili
2. BasicTextField consente agli utenti di modificare il testo tramite tastiera hardware o software, ma non fornisce decorazioni come suggerimenti o segnaposto.

@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

Stile TextField

TextField e BasicTextField condividono molti parametri comuni da personalizzare che li rappresentano. L'elenco completo per TextField è disponibile nel codice fonte di TextField. Di seguito è riportato un elenco non esaustivo di alcuni dei parametri utili:

• 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

Ti consigliamo di utilizzare TextField anziché BasicTextField quando il tuo design richiede una Materiale TextField o OutlinedTextField. Tuttavia, è necessario utilizzare BasicTextField quando si realizzano progetti che non hanno bisogno delle decorazioni della specifica Material.

Inserire lo stile con l'API Brush

Puoi utilizzare l'API Brush per stili più avanzati in TextField. La sezione seguente descrive come utilizzare un pennello per aggiungere un gradiente di colore all'input TextField.

Per ulteriori informazioni sull'uso dell'API Brush per applicare lo stile del testo, consulta Abilitare gli stili avanzati con l'API Brush.

Attenzione: l'utilizzo attuale dell'API Brush in TextStyle è sperimentale. Le API sperimentali possono cambiare in futuro.

Implementare sfumature colorate utilizzando TextStyle

Per implementare un gradiente colorato durante la digitazione all'interno di un TextField, imposta il pennello scelta come TextStyle per TextField. In questo esempio, utilizziamo pennello integrato con linearGradient per visualizzare l'effetto gradiente arcobaleno viene digitato nel 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

Nota: assicurati di utilizzare la funzione remember per far passare il pennello in modo permanente. ricomposizioni, quando lo stato TextField cambia per ogni nuovo carattere digitato.

Figura 3. Utilizzo di buildAnnotatedString, SpanStyle e linearGradient, per personalizzare solo una parte di testo.

Impostare le opzioni della tastiera

TextField ti consente di impostare le opzioni di configurazione della tastiera, ad esempio il layout della tastiera, o di attivare la correzione automatica se supportata dalla tastiera. Alcune opzioni potrebbero non essere garantite se la tastiera software non è conforme alle opzioni fornite qui. Ecco l'elenco delle opzioni della tastiera supportate:

• capitalization
• autoCorrect
• keyboardType
• imeAction

Formattare l'input

TextField ti consente di impostare un valore VisualTransformation sul valore di input, ad esempio sostituendo i caratteri con * per le password oppure inserendo trattini ogni 4 cifre per il numero di carta di credito:

@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

Altri esempi sono disponibili nel codice sorgente di VisualTransformationSamples.

Input pulito

Un'operazione comune durante la modifica del testo è rimuovere i caratteri iniziali o trasformare la stringa di input ogni volta che cambia.

Come modello, devi assumere che la tastiera possa apportare modifiche arbitrarie e di grandi dimensioni a ogni onValueChange. Ciò può accadere, ad esempio, se l'utente utilizza la correzione automatica, sostituisce una parola con un'emoji o altre funzionalità di modifica intelligente. A gestire correttamente questo aspetto, scrivere qualsiasi logica di trasformazione partendo dal presupposto che il testo attuale passato a onValueChange non è correlato al testo precedente o successivo valori che verranno passati a onValueChange.

Per implementare un campo di testo che non consenta gli zeri iniziali, puoi farlo rimuovendo tutti gli zeri iniziali per ogni variazione di valore.

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

Per controllare la posizione del cursore durante la pulizia del testo, utilizza il sovraccarico TextFieldValue di TextField nell'ambito dello stato.

Best practice per lo stato

Di seguito è riportata una serie di best practice per definire e aggiornare lo stato TextField per evitare problemi di immissione nell'app.

• Utilizza MutableState per rappresentare lo stato TextField: evita di utilizzare stream reattivi come StateFlow per rappresentare lo stato TextField, poiché queste strutture potrebbero introdurre ritardi asincroni.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}
TextSnippets.kt

• Evita ritardi per aggiornare lo stato: quando chiami il numero onValueChange, aggiorna TextField in modo sincrono e immediato:

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

• Dove definire lo stato: se lo stato TextField richiede un'attività convalide della logica durante la digitazione, è corretto sollevare lo stato nel tuo ViewModel. In caso contrario, puoi usare gli elementi componibili o una classe State holder come la fonte dei dati. Per ulteriori informazioni su dove istruire lo stato, consulta le documentazione relativa al sollevamento dello stato.

Nota: per ulteriori informazioni su queste best practice, consulta il post del blog Gestione efficace dello stato per TextField in Compose.