TextInput — какво е, въвеждане на текст и React Native

Какво е TextInput в React Native

TextInput е React Native компонент, който позволява на потребителя да въвежда текст от клавиатурата на устройството. Той е основният градивен елемент за регистрационни формуляри, ленти за търсене, полета за въвеждане на съобщения и всякакви други сценарии, изискващи потребителско въвеждане. За разлика от уеб разработката, където съществуват отделни типове input (text, email, password, search), в React Native всички тези варианти се реализират чрез един компонент TextInput с различни свойства.

TextInput поддържа два режима на работа: контролиран (управляван чрез React състояние) и неконтролиран (с ref). В контролиран режим стойността на полето се съхранява в състоянието на компонента и се актуализира чрез обратното извикване onChangeText. Този подход се препоръчва за повечето приложения, тъй като осигурява единствен източник на истина и опростява валидацията.

Според React Native Handling Text Input, 2024, TextInput автоматично се адаптира към платформата: на iOS се използва естественият UITextField, на Android — EditText. Това осигурява правилната работа на автоматичната смяна, автоматичната корекция и системните менюта (изрязване/копиране/поставяне) без допълнителна конфигурация.

Свойства и API на компонента TextInput

TextInput предоставя обширен набор от свойства за управление на въвеждането, външния вид и поведението. Всички свойства са разделени на няколко категории: управление на стойността, тип клавиатура, стилизиране, събития и платформени характеристики.

Свойства за управление на стойността

value — текущата стойност на полето (за контролиран режим). onChangeText — обратно извикване, извиквано при всяка промяна на текста. placeholder — подсказващ текст, показван когато полето е празно. defaultValue — начална стойност за неконтролиран режим. maxLength ограничава максималния брой символи, които потребителят може да въведе.

Събития на TextInput

Компонентът поддържа onFocus (полето получи фокус), onBlur (полето загуби фокус), onSubmitEditing (потребителят натисна Enter/Return), onKeyPress (натискане на клавиш). Събитието onEndEditing се извиква след завършване на редактирането при загуба на фокус. Тези обратни извиквания позволяват реализиране на сложна логика за валидация и изпращане на формуляри.

Платформени свойства

На iOS са налични: clearButtonMode (бутон за изчистване), keyboardAppearance (светла/тъмна клавиатура), returnKeyType (тип на бутона Return), enablesReturnKeyAutomatically. На Android са налични: textContentType (автоматично попълване), underlineColorAndroid, inlineImageLeft. secureTextEntry работи на двете платформи за въвеждане на пароли.

Контролирано и неконтролирано въвеждане

В React Native, TextInput може да работи в два режима. В контролиран режим, React управлява стойността на полето: вие предавате value от състоянието и го актуализирате чрез onChangeText. В неконтролиран режим, React само инициализира полето, а стойността, подобна на DOM, се съхранява вътре в естествения компонент.

Контролиран TextInput

Контролираният режим се препоръчва за всички формуляри, където е необходима валидация, филтриране или форматиране на въведените данни. Състоянието на полето е синхронизирано със състоянието на React компонента, което дава пълен контрол над стойността.

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

В този пример и двете полета използват контролиран режим. Имейлът има тип клавиатура email-address и автоматичното изписване с главни букви е изключено. Паролата използва secureTextEntry за скриване на въведените символи и е ограничена до 32 символа чрез maxLength.

Неконтролиран TextInput

Неконтролираният режим е подходящ за прости полета, където не е необходима валидация или незабавна реакция на въвеждане. Стойността на полето се извлича чрез ref в момента на изпращане на формуляра.

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

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

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

В неконтролиран режим компонентът се рендерира по-бързо, тъй като не изисква синхронизация на състоянието при всяка промяна на текста. Въпреки това, губите възможността да филтрирате, форматирате или валидирате въвеждането в реално време.

Типове клавиатура и платформени характеристики

TextInput поддържа различни типове клавиатура, които адаптират оформлението към очаквания формат на въвеждане. Изборът на правилния тип клавиатура подобрява потребителското изживяване и намалява броя на грешките при въвеждане на мобилни устройства.

На iOS са налични допълнителни типове: numbers-and-punctuation (цифри и пунктуация), twitter, web-search (с гласово търсене). На Android също е наличен visible-password (показва паролата). Правилният избор на keyboardType е важен аспект на UX на мобилното приложение.

Платформените характеристики включват също autoCapitalize (автоматично изписване с главна буква на първата дума), autoCorrect (автоматична корекция), spellCheck (проверка на правописа), textContentType (автоматично попълване на iOS). Тези свойства работят различно на всяка платформа и изискват тестване.

Практически примери с TextInput

Нека разгледаме два реални сценария: многоредово поле за въвеждане на съобщение и поле с маскирано въвеждане на телефонен номер. И двата използват TextInput с различни свойства за постигане на желаното поведение.

Пример 1: многоредово поле за съобщение

За въвеждане на дълъг текст (коментари, описание) TextInput превключва в многоредов режим чрез свойството multiline. В този режим полето расте вертикално и поддържа прекъсване на редове.

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

Свойството multiline включва многоредов режим, numberOfLines задава началната височина в редове. textAlignVertical: 'top' подравнява текста към горния ръб (по подразбиране на Android многоредовият TextInput центрира текста вертикално).

Пример 2: поле с форматиране на телефонен номер

За въвеждане на телефонен номер често се изисква форматиране в реално време. Чрез комбиниране на onChangeText с регулярни изрази може да се реализира маска за въвеждане.

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

Функцията formatPhone премахва всички нецифрови символи и форматира номера в стандартен международен формат. keyboardType: 'phone-pad' показва телефонната клавиатура. Такъв подход подобрява UX за въвеждане на телефонни номера и предотвратява грешки при форматиране.