TextInput — ce este, introducerea textului și React Native

Ce este TextInput în React Native

TextInput este o componentă React Native care permite utilizatorului să introducă text de pe tastatura dispozitivului. Este elementul principal pentru formulare de înregistrare, bare de căutare, câmpuri de introducere a mesajelor și orice alte scenarii care necesită introducere de date de către utilizator. Spre deosebire de dezvoltarea web, unde există tipuri separate de input (text, email, password, search), în React Native toate aceste variante sunt implementate printr-o singură componentă TextInput cu diferite proprietăți.

TextInput suportă două moduri de lucru: controlat (gestionat prin starea React) și necontrolat (cu referință). În modul controlat, valoarea câmpului este stocată în starea componentei și actualizată prin callback-ul onChangeText. Această abordare este recomandată pentru majoritatea aplicațiilor, deoarece asigură o singură sursă de adevăr și simplifică validarea.

Conform React Native Handling Text Input, 2024, TextInput se adaptează automat la platformă: pe iOS se utilizează UITextField nativ, pe Android — EditText. Aceasta asigură funcționarea corectă a înlocuirii automate, autocorectării și meniurilor de sistem (taiere/copiere/lipire) fără configurare suplimentară.

Proprietăți și API ale componentei TextInput

TextInput oferă un set extins de proprietăți pentru gestionarea introducerii, aspectului și comportamentului. Toate proprietățile sunt împărțite în mai multe categorii: gestionarea valorii, tipul tastaturii, stilizare, evenimente și particularități de platformă.

Proprietăți de gestionare a valorii

value — valoarea curentă a câmpului (pentru modul controlat). onChangeText — callback apelat la fiecare modificare a textului. placeholder — text sugestiv afișat când câmpul este gol. defaultValue — valoarea inițială pentru modul necontrolat. maxLength limitează numărul maxim de caractere pe care utilizatorul le poate introduce.

Evenimente TextInput

Componenta suportă onFocus (câmpul a primit focalizarea), onBlur (câmpul a pierdut focalizarea), onSubmitEditing (utilizatorul a apăsat Enter/Return), onKeyPress (apăsarea unei taste). Evenimentul onEndEditing este apelat după încheierea editării la pierderea focalizării. Aceste callback-uri permit implementarea unei logici complexe de validare și trimitere a formularelor.

Proprietăți de platformă

Pe iOS sunt disponibile: clearButtonMode (buton de ștergere), keyboardAppearance (tastatură deschisă/închisă), returnKeyType (tipul butonului Return), enablesReturnKeyAutomatically. Pe Android sunt disponibile: textContentType (completare automată), underlineColorAndroid, inlineImageLeft. secureTextEntry funcționează pe ambele platforme pentru introducerea parolelor.

Introducere controlată și necontrolată

În React Native, TextInput poate funcționa în două moduri. În modul controlat, React gestionează valoarea câmpului: trimiteți value din stare și o actualizați prin onChangeText. În modul necontrolat, React doar inițializează câmpul, iar valoarea asemănătoare DOM-ului este stocată în interiorul componentei native.

TextInput controlat

Modul controlat este recomandat pentru toate formularele care necesită validare, filtrare sau formatare a datelor introduse. Starea câmpului este sincronizată cu starea componentei React, oferind control complet asupra valorii.

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

În acest exemplu, ambele câmpuri utilizează modul controlat. Email are tipul de tastatură email-address și capitalizarea automată dezactivată. Parola utilizează secureTextEntry pentru ascunderea caracterelor introduse și este limitată la 32 de caractere prin maxLength.

TextInput necontrolat

Modul necontrolat este potrivit pentru câmpuri simple unde nu este necesară validarea sau reacția imediată la introducere. Valoarea câmpului este extrasă prin referință în momentul trimiterii formularului.

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

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

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

În modul necontrolat, componenta se redează mai rapid, deoarece nu necesită sincronizarea stării la fiecare modificare a textului. Cu toate acestea, pierdeți posibilitatea de a filtra, formata sau valida introducerea în timp real.

Tipuri de tastatură și particularități de platformă

TextInput suportă diferite tipuri de tastatură care adaptează aspectul la formatul de introducere așteptat. Alegerea tipului corect de tastatură îmbunătățește experiența utilizatorului și reduce numărul de erori de introducere pe dispozitivele mobile.

Pe iOS sunt disponibile tipuri suplimentare: numbers-and-punctuation (cifre și punctuație), twitter, web-search (cu căutare vocală). Pe Android este disponibil și visible-password (afișează parola). Alegerea corectă a keyboardType este un aspect important al UX al aplicației mobile.

Particularitățile de platformă includ, de asemenea, autoCapitalize (capitalizarea automată a primului cuvânt), autoCorrect (autocorectare), spellCheck (verificare ortografică), textContentType (completare automată pe iOS). Aceste proprietăți funcționează diferit pe fiecare platformă și necesită testare.

Exemple practice cu TextInput

Să analizăm două scenarii reale: un câmp multi-linie pentru introducerea mesajelor și un câmp cu introducere mascată a numărului de telefon. Ambele utilizează TextInput cu diferite proprietăți pentru a obține comportamentul dorit.

Exemplul 1: câmp multi-linie pentru mesaj

Pentru introducerea textului lung (comentarii, descriere), TextInput comută în modul multi-linie prin proprietatea multiline. În acest mod, câmpul crește vertical și suportă întreruperea liniilor.

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"
        />
    );
};

Proprietatea multiline activează modul multi-linie, numberOfLines stabilește înălțimea inițială în linii. textAlignVertical: 'top' aliniază textul la marginea superioară (implicit pe Android, TextInput multi-linie centrează textul vertical).

Exemplul 2: câmp cu formatare a numărului de telefon

Pentru introducerea numărului de telefon este adesea necesară formatarea în timp real. Combinând onChangeText cu expresii regulate, se poate implementa o mască de introducere.

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}
        />
    );
};

Funcția formatPhone elimină toate caracterele ne-digitale și formatează numărul în format internațional standard. keyboardType: 'phone-pad' afișează tastatura telefonică. O astfel de abordare îmbunătățește UX pentru introducerea numerelor de telefon și previne erorile de formatare.