Configurare i campi di testo

TextField consente agli utenti di inserire e modificare il testo. Esistono due tipi di campi di testo che puoi utilizzare: campi di testo basati sullo stato e campi di testo basati sul valore. Seleziona il tipo di contenuti che vuoi visualizzare:

Ti consigliamo di utilizzare i campi di testo basati sullo stato, in quanto forniscono un approccio più completo e affidabile per la gestione dello stato di un TextField. La seguente tabella illustra le differenze tra questi tipi di campi di testo e include i principali vantaggi offerti dai campi di testo basati sullo stato:

Funzionalità

Campi di testo basati sul valore

Campi di testo basati sullo stato

Vantaggio basato sullo stato

Gestione dello stato

Aggiorna lo stato del campo di testo con il callback onValueChange. Sei responsabile dell'aggiornamento di value nel tuo stato in base alle modifiche segnalate da onValueChange.

Utilizza esplicitamente un oggetto TextFieldState per gestire lo stato di inserimento del testo (valore, selezione e composizione). Questo stato può essere memorizzato e condiviso.
  • Il callback onValueChange è stato rimosso, il che impedisce di introdurre comportamenti asincroni.
  • Lo stato sopravvive alla ricomposizione, alla configurazione e all'interruzione del processo.

Trasformazione visiva

Utilizza VisualTransformation per modificare l'aspetto del testo visualizzato. In genere, questo gestisce la formattazione di input e output in un unico passaggio.

Utilizza InputTransformation per modificare l'input dell'utente prima che venga eseguito il commit nello stato e OutputTransformation per formattare i contenuti del campo di testo senza modificare i dati dello stato sottostanti.
  • Non è più necessario fornire la mappatura dell'offset tra il testo non elaborato originale e il testo trasformato con OutputTransformation.

Limiti delle linee

Accetta singleLine: Boolean, maxLines: Int e minLines: Int per controllare il numero di righe.

Utilizza lineLimits: TextFieldLineLimits per configurare il numero minimo e massimo di righe che il campo di testo può occupare.
  • Rimuove l'ambiguità durante la configurazione dei limiti di riga fornendo un parametro lineLimits di tipo TextFieldLineLimits.

Campo di testo sicuro

N/D

SecureTextField è un componibile basato su campi di testo basati sullo stato per la scrittura di un campo password.
  • Ti consente di ottimizzare la sicurezza in background e include una UI predefinita con textObfuscationMode.

Questa pagina descrive come implementare TextField, applicare uno stile all'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 quanto segue le linee guida di Material Design:
    • Lo stile predefinito è filled
    • OutlinedTextField è la versione di stile outlined
  2. BasicTextField consente agli utenti di modificare il testo utilizzando la tastiera hardware o la tastiera su schermo, ma non fornisce decorazioni come suggerimenti o segnaposto.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)

Un campo di testo modificabile contenente la parola 

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

Un campo di testo modificabile, con un bordo e un'etichetta viola.

Stile TextField

TextField e BasicTextField condividono molti parametri comuni per la personalizzazione. L'elenco completo per TextField è disponibile nel codice sorgente TextField. Questo è un elenco non esaustivo di alcuni dei parametri utili:

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

Un TextField multilinea, con due righe modificabili più l'etichetta

Ti consigliamo di utilizzare TextField anziché BasicTextField quando il tuo design richiede un TextField o un OutlinedTextField di Material. Tuttavia, BasicTextField deve essere utilizzato quando si creano design che non richiedono le decorazioni della specifica Material.

Stile dell'input con l'API Brush

Puoi utilizzare l'API Brush per uno stile più avanzato nel tuo TextField. La sezione seguente descrive come utilizzare un pennello per aggiungere un gradiente di colore all'input TextField.

Per saperne di più sull'utilizzo dell'API Brush per applicare uno stile al testo, consulta Attiva lo stile avanzato con l'API Brush.

Implementa i gradienti colorati utilizzando TextStyle

Per implementare una mappa a gradiente di colore durante la digitazione all'interno di un TextField, imposta il pennello che preferisci come TextStyle per il tuo TextField. In questo esempio, utilizziamo un pennello integrato con un linearGradient per visualizzare l'effetto gradiente arcobaleno mentre il testo viene digitato nel 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)
)

Testo digitato in un campo di testo, con un effetto gradiente arcobaleno.
Figura 1. Un effetto gradiente arcobaleno per i contenuti di TextField.

Gestisci lo stato dei campi di testo

TextField utilizza una classe contenitore di stato dedicata denominata TextFieldState per i contenuti e la selezione. TextFieldState è progettato per essere inserito ovunque si adatti alla tua architettura. TextFieldState fornisce due proprietà principali:

  • initialText: i contenuti di TextField.
  • initialSelection: indica dove si trova il cursore o la selezione.

Ciò che distingue TextFieldState da altri approcci, come il callback onValueChange, è che TextFieldState incapsula completamente l'intero flusso di input. Ciò include l'utilizzo delle strutture di dati di supporto corrette, l'incorporamento di filtri e formattatori e la sincronizzazione di tutte le modifiche provenienti da fonti diverse.

Puoi utilizzare TextFieldState() per eseguire l'hoisting dello stato in TextField. Per questo, ti consigliamo di utilizzare la funzione rememberTextFieldState(). rememberTextFieldState() crea l'istanza TextFieldState nel tuo composable, si assicura che l'oggetto di stato venga memorizzato e fornisce funzionalità di salvataggio e ripristino integrate:

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

rememberTextFieldState può avere un parametro vuoto o un valore iniziale passato per rappresentare il valore del testo durante l'inizializzazione. Se viene passato un valore diverso in una ricomposizione successiva, il valore dello stato non viene aggiornato. Per aggiornare lo stato dopo l'inizializzazione, chiama i metodi di modifica su TextFieldState.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)

Un TextField con il testo Nome utente visualizzato all'interno del campo di testo.
Figura 2. TextField con "Nome utente" come testo iniziale.

Modifica il testo con TextFieldBuffer

Un TextFieldBuffer funge da contenitore di testo modificabile, con una funzione simile a un StringBuilder. Contiene sia i contenuti testuali sia le informazioni sulla selezione.

Spesso incontri TextFieldBuffer come ambito del ricevitore su funzioni come TextFieldState.edit, InputTransformation.transformInput o OutputTransformation.transformOutput. In queste funzioni, puoi leggere o aggiornare TextFieldBuffer in base alle tue esigenze. In seguito, viene eseguito il commit di queste modifiche in TextFieldState o vengono passate alla pipeline di rendering nel caso di OutputTransformation.

Puoi utilizzare le funzioni di modifica standard come append, insert, replace o delete per modificare i contenuti del buffer. Per modificare lo stato di selezione, imposta direttamente la variabile selection: TextRange o utilizza funzioni di utilità come placeCursorAtEnd o selectAll. La selezione stessa è rappresentata da un TextRange, dove l'indice iniziale è incluso e l'indice finale è escluso. Un TextRange con valori di inizio e fine identici, come (3, 3), indica una posizione del cursore senza caratteri selezionati.

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

Modifica il testo in TextFieldState

Esistono diversi metodi che ti consentono di modificare lo stato direttamente tramite la variabile di stato:

  • edit: consente di modificare i contenuti dello stato e fornisce funzioni TextFieldBuffer per utilizzare metodi come insert, replace, append e altri.

    // 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: cancella il testo corrente, lo sostituisce con il testo specificato e imposta il cursore alla fine.

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

  • clearText: cancella tutto il testo.

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

Per altre funzioni TextFieldState, consulta il riferimento TextFieldState.

Modifica l'input dell'utente

Le sezioni seguenti descrivono come modificare l'input dell'utente. La trasformazione dell'input ti consente di filtrare l'input di TextField mentre l'utente digita, mentre la trasformazione dell'output formatta l'input dell'utente prima che venga visualizzato sullo schermo.

Filtra l'input utente con le trasformazioni di input

Una trasformazione di input consente di filtrare l'input dell'utente. Ad esempio, se il tuo TextField accetta un numero di telefono americano, vuoi accettare solo 10 cifre. I risultati di InputTransformation vengono salvati in TextFieldState.

Sono disponibili filtri integrati per i casi d'uso comuni di InputTransformation. Per limitare la lunghezza, chiama InputTransformation.maxLength():

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)

Trasformazioni di input personalizzate

InputTransformation è un'interfaccia con una singola funzione. Quando implementi il tuo InputTransformation personalizzato, devi eseguire l'override di TextFieldBuffer.transformInput:

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

Per un numero di telefono, aggiungi una trasformazione dell'input personalizzata che consenta di digitare solo cifre nel campo TextField:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}

Concatena le trasformazioni di input

Per aggiungere più filtri all'input di testo, concatena i InputTransformation utilizzando la funzione di estensione then. I filtri vengono eseguiti in sequenza. Come best practice, applica prima i filtri più selettivi per evitare trasformazioni non necessarie sui dati che alla fine verrebbero filtrati.

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

Dopo aver aggiunto le trasformazioni di input, l'input TextField accetta un massimo di 10 cifre.

Formatta l'input prima che venga visualizzato

OutputTransformation ti consente di formattare l'input dell'utente prima che venga visualizzato sullo schermo. A differenza di InputTransformation, la formattazione eseguita tramite OutputTransformation non viene salvata in TextFieldState. Sulla base dell'esempio di numero di telefono precedente, devi aggiungere parentesi e trattini nei punti appropriati:

Un numero di telefono statunitense, formattato correttamente con parentesi, trattini e indici corrispondenti.
Figura 3. Un numero di telefono americano con la formattazione corretta e gli indici corrispondenti.

Questo è il modo aggiornato di gestire i VisualTransformation nei TextField basati sul valore, con una differenza fondamentale: non è necessario calcolare le mappature degli offset.

OutputTransformation è un'interfaccia di un singolo metodo astratto. Per implementare un OutputTransformation personalizzato, devi eseguire l'override del metodo transformOutput:

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

Per formattare un numero di telefono, aggiungi una parentesi di apertura all'indice 0, una parentesi di chiusura all'indice 4 e un trattino all'indice 8 al tuo OutputTransformation:

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

Poi, aggiungi OutputTransformation a TextField:

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

Come interagiscono le trasformazioni

Il seguente diagramma mostra il flusso dall'input di testo alla trasformazione fino all'output:

Una visualizzazione di come l'input di testo viene trasformato prima di diventare l'output di testo.
Figura 4. Un diagramma che mostra come l'input di testo viene trasformato prima di diventare l'output di testo.
  1. L'input viene ricevuto dalla sorgente di ingresso.
  2. L'input viene filtrato tramite un InputTransformation, che viene salvato in TextFieldState.
  3. L'input viene passato tramite un OutputTransformation per la formattazione.
  4. L'input viene presentato in TextField.

Imposta le opzioni della tastiera

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

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Risorse aggiuntive