TextInput — что это, ввод текста и React Native

Что такое TextInput в React Native

TextInput — это компонент React Native, который позволяет пользователю вводить текст с клавиатуры устройства. Он является основным строительным блоком для форм регистрации, поисковых строк, полей ввода сообщений и любых других сценариев, где требуется пользовательский ввод. В отличие от веб-разработки, где существуют отдельные типы input (text, email, password, search), в React Native все эти варианты реализуются через один компонент TextInput с разными пропсами.

TextInput поддерживает два режима работы: контролируемый (управляемый через состояние React) и неконтролируемый (с рефом). В контролируемом режиме значение поля хранится в состоянии компонента и обновляется через коллбэк 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 имеет тип клавиатуры email-address и отключённый автокапитал. Пароль использует secureTextEntry для скрытия вводимых символов и ограничен 32 символами через maxLength.

Неконтролируемый TextInput

Неконтролируемый режим подходит для простых полей, где не нужна валидация или моментальная реакция на ввод. Значение поля извлекается через реф в момент отправки формы.

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 для ввода телефонных номеров и предотвращает ошибки форматирования.