TextInput — che cos'è, input di testo e React Native

Cos'è TextInput in React Native

TextInput è un componente React Native che consente agli utenti di inserire testo utilizzando la tastiera del dispositivo. È il mattone fondamentale per moduli di registrazione, barre di ricerca, campi di inserimento messaggi e qualsiasi altro scenario che richieda input utente. A differenza dello sviluppo web, dove esistono tipi di input separati (text, email, password, search), in React Native tutte queste varianti vengono implementate attraverso un singolo componente TextInput con diverse props.

TextInput supporta due modalità di funzionamento: controllata (gestita tramite lo stato React) e non controllata (utilizzando una ref). In modalità controllata, il valore del campo viene memorizzato nello stato del componente e aggiornato tramite il callback onChangeText. Questo approccio è raccomandato per la maggior parte delle applicazioni poiché fornisce un'unica fonte di verità e semplifica la validazione.

Secondo React Native Handling Text Input, 2024, TextInput si adatta automaticamente alla piattaforma: su iOS utilizza UITextField nativo, su Android — EditText. Ciò garantisce il corretto funzionamento dell'autocompletamento, della correzione automatica e dei menu di sistema (taglia/copia/incolla) senza configurazione aggiuntiva.

Proprietà e API di TextInput

TextInput fornisce un set esteso di props per controllare l'input, l'aspetto e il comportamento. Tutte le props sono divise in diverse categorie: gestione del valore, tipo di tastiera, stile, eventi e funzionalità specifiche della piattaforma.

Props di gestione del valore

value — il valore corrente del campo (per la modalità controllata). onChangeText — callback invocato ad ogni modifica del testo. placeholder — testo suggerito visualizzato quando il campo è vuoto. defaultValue — valore iniziale per la modalità non controllata. maxLength limita il numero massimo di caratteri che l'utente può inserire.

Eventi di TextInput

Il componente supporta onFocus (il campo ha ricevuto il focus), onBlur (il campo ha perso il focus), onSubmitEditing (l'utente ha premuto Invio/Return), onKeyPress (pressione di un tasto). L'evento onEndEditing viene chiamato dopo il completamento della modifica quando si perde il focus. Questi callback consentono di implementare logiche complesse di validazione e invio di moduli.

Props specifiche della piattaforma

Su iOS: clearButtonMode (pulsante di cancellazione), keyboardAppearance (tastiera chiara/scura), returnKeyType (tipo di pulsante Return), enablesReturnKeyAutomatically. Su Android: textContentType (compilazione automatica), underlineColorAndroid, inlineImageLeft. secureTextEntry funziona su entrambe le piattaforme per l'input di password.

Input controllato e non controllato

In React Native, TextInput può funzionare in due modalità. In modalità controllata, React gestisce il valore del campo: passi il valore dallo stato e lo aggiorni tramite onChangeText. In modalità non controllata, React inizializza solo il campo e il valore simile al DOM viene memorizzato all'interno del componente nativo.

TextInput controllato

La modalità controllata è raccomandata per tutti i form che richiedono validazione, filtraggio o formattazione dei dati inseriti. Lo stato del campo è sincronizzato con lo stato del componente React, fornendo il controllo completo sul valore.

const LoginForm = () => {
    const [email, setEmail] = useState('');
    const [password, setPassword] = useState('');

    return (
        <View>
            <TextInput
                placeholder="Email"
                value={email}
                onChangeText={setEmail}
                keyboardType="email-address"
                autoCapitalize="none"
            />
            <TextInput
                placeholder="Password"
                value={password}
                onChangeText={setPassword}
                secureTextEntry
                maxLength={32}
            />
        </View>
    );
};

In questo esempio, entrambi i campi utilizzano la modalità controllata. Il campo email ha il tipo di tastiera email-address e la capitalizzazione automatica disattivata. Il campo password utilizza secureTextEntry per nascondere i caratteri inseriti ed è limitato a 32 caratteri tramite maxLength.

TextInput non controllato

La modalità non controllata è adatta per campi semplici che non richiedono validazione o reazione immediata all'input. Il valore del campo viene recuperato tramite una ref al momento dell'invio del modulo.

const SimpleSearch = () => {
    const inputRef = useRef(null);

    const handleSearch = () => {
        console.log(inputRef.current.value());
    };

    return (
        <TextInput
            ref={inputRef}
            placeholder="Search..."
            onSubmitEditing={handleSearch}
        />
    );
};

In modalità non controllata, il componente viene renderizzato più velocemente poiché non richiede la sincronizzazione dello stato ad ogni modifica del testo. Tuttavia, si perde la capacità di filtrare, formattare o validare l'input in tempo reale.

Tipi di tastiera e caratteristiche della piattaforma

TextInput supporta vari tipi di tastiera che adattano il layout al formato di input previsto. Scegliere il tipo di tastiera corretto migliora l'esperienza utente e riduce gli errori di input sui dispositivi mobili.

Su iOS sono disponibili tipi aggiuntivi: numbers-and-punctuation, twitter, web-search (con ricerca vocale). Su Android è disponibile anche visible-password (mostra la password). Scegliere il keyboardType corretto è un aspetto importante dell'UX delle applicazioni mobili.

Le caratteristiche della piattaforma includono anche autoCapitalize (capitalizzazione automatica della prima parola), autoCorrect (correzione automatica), spellCheck (controllo ortografico), textContentType (compilazione automatica su iOS). Queste props funzionano diversamente su ciascuna piattaforma e richiedono test.

Esempi pratici con TextInput

Consideriamo due scenari reali: un campo multilinea per l'inserimento di messaggi e un campo con maschera per il numero di telefono. Entrambi utilizzano TextInput con diverse props per ottenere il comportamento desiderato.

Esempio 1: Campo multilinea per messaggio

Per inserire testo lungo (commenti, descrizioni), TextInput passa alla modalità multilinea tramite la prop multiline. In questa modalità, il campo cresce verticalmente e supporta interruzioni di riga.

const MessageInput = ({ onSend }) => {
    const [text, setText] = useState('');

    return (
        <TextInput
            style={styles.input}
            multiline
            numberOfLines={4}
            placeholder="Write a message..."
            value={text}
            onChangeText={setText}
            textAlignVertical="top"
        />
    );
};

La prop multiline attiva la modalità multilinea, numberOfLines imposta l'altezza iniziale in righe. textAlignVertical: 'top' allinea il testo in alto (per impostazione predefinita, su Android TextInput multilinea centra il testo verticalmente).

Esempio 2: Campo con formattazione del numero di telefono

Per inserire un numero di telefono, spesso è necessaria la formattazione in tempo reale. Combinando onChangeText con espressioni regolari, è possibile implementare una maschera di input.

const PhoneInput = () => {
    const [phone, setPhone] = useState('');

    const formatPhone = (text) => {
        const cleaned = text.replace(/\D/g, '');
        if (cleaned.length <= 11) {
            return cleaned.replace(
                /(\d{1})(\d{3})(\d{3})(\d{2})(\d{2})/,
                '+$1 ($2) $3 $4 $5'
            );
        }
        return cleaned;
    };

    return (
        <TextInput
            keyboardType="phone-pad"
            value={phone}
            onChangeText={(t) => setPhone(formatPhone(t))}
            placeholder="+7 (999) 123 45 67"
            maxLength={20}
        />
    );
};

La funzione formatPhone rimuove tutti i caratteri non numerici e formatta il numero in un formato internazionale standard. keyboardType: 'phone-pad' mostra la tastiera telefonica. Questo approccio migliora l'UX per l'inserimento di numeri di telefono e previene errori di formattazione.