TextInput — co to jest, wprowadzanie tekstu i React Native

Co to jest TextInput w React Native

TextInput — to komponent React Native, który pozwala użytkownikowi wprowadzać tekst z klawiatury urządzenia. Jest podstawowym elementem do formularzy rejestracyjnych, pól wyszukiwania, pól do wprowadzania wiadomości i wszelkich innych scenariuszy wymagających wprowadzania danych przez użytkownika. W przeciwieństwie do tworzenia stron internetowych, gdzie istnieją osobne typy input (text, email, password, search), w React Native wszystkie te warianty są realizowane przez jeden komponent TextInput z różnymi właściwościami.

TextInput obsługuje dwa tryby pracy: kontrolowany (zarządzany przez stan React) i niekontrolowany (z referencją). W trybie kontrolowanym wartość pola jest przechowywana w stanie komponentu i aktualizowana przez callback onChangeText. To podejście jest zalecane dla większości aplikacji, ponieważ zapewnia jeden źródło prawdy i upraszcza walidację.

Według React Native Handling Text Input, 2024, TextInput automatycznie dostosowuje się do platformy: na iOS używany jest natywny UITextField, na Androidzie — EditText. Zapewnia to poprawne działanie autopodmiany, autokorekty i menu systemowych (wytnij/kopiuj/wklej) bez dodatkowej konfiguracji.

Właściwości i API komponentu TextInput

TextInput zapewnia obszerny zestaw właściwości do zarządzania wprowadzaniem, wyglądem i zachowaniem. Wszystkie właściwości dzielą się na kilka kategorii: zarządzanie wartością, typ klawiatury, stylizacja, zdarzenia i cechy platformowe.

Właściwości zarządzania wartością

value — bieżąca wartość pola (dla trybu kontrolowanego). onChangeText — callback wywoływany przy każdej zmianie tekstu. placeholder — tekst podpowiedzi wyświetlany, gdy pole jest puste. defaultValue — wartość początkowa dla trybu niekontrolowanego. maxLength ogranicza maksymalną liczbę znaków, które może wprowadzić użytkownik.

Zdarzenia TextInput

Komponent obsługuje onFocus (pole otrzymało fokus), onBlur (pole straciło fokus), onSubmitEditing (użytkownik nacisnął Enter/Return), onKeyPress (naciśnięcie klawisza). Zdarzenie onEndEditing jest wywoływane po zakończeniu edycji przy utracie fokusu. Te callbacki umożliwiają implementację złożonej logiki walidacji i wysyłania formularzy.

Właściwości platformowe

Na iOS dostępne są: clearButtonMode (przycisk czyszczenia), keyboardAppearance (jasna/ciemna klawiatura), returnKeyType (typ przycisku Return), enablesReturnKeyAutomatically. Na Androidzie dostępne są: textContentType (autouzupełnianie), underlineColorAndroid, inlineImageLeft. secureTextEntry działa na obu platformach do wprowadzania haseł.

Wprowadzanie kontrolowane i niekontrolowane

W React Native TextInput może działać w dwóch trybach. W trybie kontrolowanym React zarządza wartością pola: przekazujesz value ze stanu i aktualizujesz je przez onChangeText. W trybie niekontrolowanym React tylko inicjalizuje pole, a wartość podobna do DOM jest przechowywana wewnątrz natywnego komponentu.

Kontrolowany TextInput

Tryb kontrolowany jest zalecany dla wszystkich formularzy, gdzie potrzebna jest walidacja, filtrowanie lub formatowanie wprowadzanych danych. Stan pola jest zsynchronizowany ze stanem komponentu React, co daje pełną kontrolę nad wartością.

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

W tym przykładzie oba pola używają trybu kontrolowanego. Email ma typ klawiatury email-address i wyłączoną automatyczną kapitalizację. Hasło używa secureTextEntry do ukrywania wprowadzanych znaków i jest ograniczone do 32 znaków przez maxLength.

Niekontrolowany TextInput

Tryb niekontrolowany nadaje się do prostych pól, gdzie nie jest potrzebna walidacja lub natychmiastowa reakcja na wprowadzanie. Wartość pola jest pobierana przez referencję w momencie wysyłania formularza.

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

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

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

W trybie niekontrolowanym komponent renderuje się szybciej, ponieważ nie wymaga synchronizacji stanu przy każdej zmianie tekstu. Jednak tracisz możliwość filtrowania, formatowania lub walidowania wprowadzanych danych w czasie rzeczywistym.

Typy klawiatury i cechy platformowe

TextInput obsługuje różne typy klawiatury, które dostosowują układ do oczekiwanego formatu wprowadzania. Wybór odpowiedniego typu klawiatury poprawia doświadczenie użytkownika i zmniejsza liczbę błędów wprowadzania na urządzeniach mobilnych.

Na iOS dostępne są dodatkowe typy: numbers-and-punctuation (cyfry i interpunkcja), twitter, web-search (z wyszukiwaniem głosowym). Na Androidzie dostępny jest również visible-password (pokazuje hasło). Wybór odpowiedniego keyboardType to ważny aspekt UX aplikacji mobilnej.

Cechy platformowe obejmują również autoCapitalize (automatyczna kapitalizacja pierwszego słowa), autoCorrect (autokorekta), spellCheck (sprawdzanie pisowni), textContentType (autouzupełnianie na iOS). Te właściwości działają inaczej na każdej platformie i wymagają testowania.

Praktyczne przykłady z TextInput

Rozpatrzmy dwa rzeczywiste scenariusze: pole wieloliniowe do wprowadzania wiadomości i pole z maskowanym wprowadzaniem numeru telefonu. Oba używają TextInput z różnymi właściwościami do osiągnięcia pożądanego zachowania.

Przykład 1: pole wieloliniowe do wiadomości

Do wprowadzania długiego tekstu (komentarze, opis) TextInput przełącza się w tryb wieloliniowy przez właściwość multiline. W tym trybie pole rośnie pionowo i obsługuje przenoszenie wierszy.

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

Właściwość multiline włącza tryb wieloliniowy, numberOfLines ustawia początkową wysokość w wierszach. textAlignVertical: 'top' wyrównuje tekst do górnej krawędzi (domyślnie na Androidzie wieloliniowy TextInput centruje tekst pionowo).

Przykład 2: pole z formatowaniem numeru telefonu

Do wprowadzania numeru telefonu często wymagane jest formatowanie w czasie rzeczywistym. Łącząc onChangeText z wyrażeniami regularnymi, można zaimplementować maskę wprowadzania.

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

Funkcja formatPhone usuwa wszystkie niecyfrowe znaki i formatuje numer w standardowym międzynarodowym formacie. keyboardType: 'phone-pad' wyświetla klawiaturę telefoniczną. Takie podejście poprawia UX przy wprowadzaniu numerów telefonów i zapobiega błędom formatowania.