TextInput

Базовый компонент для ввода текста в приложение с помощью клавиатуры. Свойства позволяют настроить различные функции, такие как автоисправление, автозаглавие, текст подсказки и различные типы клавиатур, например, числовая клавиатура.

Наиболее простой сценарий использования — размещение TextInput и подписка на события onChangeText для чтения пользовательского ввода. Также доступны другие события, такие как onSubmitEditing и onFocus, на которые можно подписаться. Пример минимального использования:

Два метода, доступные через собственный элемент, — .focus() и .blur(), которые позволяют программно установить или снять фокус с TextInput.

Обратите внимание, что некоторые свойства доступны только с multiline={true/false}. Кроме того, стили границы, которые применяются только к одной стороне элемента (например, borderBottomColor, borderLeftWidth, и т. д.), не будут применяться, если multiline=true. Чтобы добиться такого же эффекта, можно обернуть свой TextInput в View.

TextInput по умолчанию имеет границу в нижней части своего представления. Отступ этой границы определяется фоновым изображением, предоставляемым системой, и его нельзя изменить. Решения для избежания этого заключаются в том, чтобы либо не устанавливать высоту явно, в этом случае система позаботится о правильном отображении границы, либо не отображать границу, установив underlineColorAndroid в прозрачный цвет.

Обратите внимание, что на Android при выделении текста в поле ввода параметр активности приложения windowSoftInputMode может измениться на adjustResize. Это может привести к проблемам с компонентами, у которых свойство position: 'absolute', когда активна клавиатура. Чтобы избежать этого поведения, укажите windowSoftInputMode в файле AndroidManifest.xml ( https://developer.android.com/guide/topics/manifest/activity-element.html) или управляйте этим параметром программно с помощью кода нативных языках.

Справочник

Свойства

Свойства View

Наследует Свойства View.

allowFontScaling

Указывает, следует ли масштабировать шрифты с учетом настроек доступности размера текста. По умолчанию значение true.

autoCapitalize

Указывает TextInput на автоматическое приведение определенных символов к верхнему регистру. Это свойство не поддерживается некоторыми типами клавиатур, такими как name-phone-pad.

• characters: все символы.
• words: первая буква каждого слова.
• sentences: первая буква каждого предложения (по умолчанию).
• none: не производить автоматическое приведение к верхнему регистру.

autoComplete

Android

Указывает подсказки автозаполнения для системы, чтобы она могла предложить автозаполнение. На Android система всегда пытается предложить автозаполнение, используя эвристику для определения типа содержимого. Чтобы отключить автозаполнение, установите autoComplete в off.

Возможные значения для autoComplete:

• birthdate-day
• birthdate-full
• birthdate-month
• birthdate-year
• cc-csc
• cc-exp
• cc-exp-day
• cc-exp-month
• cc-exp-year
• cc-number
• email
• gender
• name
• name-family
• name-given
• name-middle
• name-middle-initial
• name-prefix
• name-suffix
• password
• password-new
• postal-address
• postal-address-country
• postal-address-extended
• postal-address-extended-postal-code
• postal-address-locality
• postal-address-region
• postal-code
• street-address
• sms-otp
• tel
• tel-country-code
• tel-national
• tel-device
• username
• username-new
• off

autoCorrect

Если false, отключает автоисправление. Значение по умолчанию true.

autoFocus

Если true, устанавливает фокус на поле ввода при componentDidMount или useEffect . Значение по умолчанию false.

blurOnSubmit

Если true, поле ввода будет снимать фокус при отправке. Значение по умолчанию — true для однострочных полей и false для многострочных полей. Обратите внимание, что для многострочных полей, установка blurOnSubmit в true означает, что нажатие клавиши ввода будет снимать фокус с поля и вызывать событие onSubmitEditing вместо вставки новой строки в поле.

caretHidden

Если true, курсор скрыт. Значение по умолчанию false.

clearButtonMode

iOS

Когда должна отображаться кнопка очистки в правой части поля ввода. Это свойство поддерживается только для компонента TextInput с одной строкой. Значение по умолчанию never.

clearTextOnFocus

iOS

Если true, поле ввода автоматически очищается при начале редактирования.

contextMenuHidden

Если true, контекстное меню скрыто. Значение по умолчанию false.

dataDetectorTypes

iOS

Определяет типы данных, преобразуемых в нажатия по URL в поле ввода. Действительно только если multiline={true} и editable={false}. По умолчанию типы данных не обнаруживаются.

Можно указать один тип или массив из нескольких типов.

Возможные значения для dataDetectorTypes:

• 'phoneNumber'
• 'link'
• 'address'
• 'calendarEvent'
• 'none'
• 'all'

defaultValue

Предоставляет начальное значение, которое изменяется при вводе пользователем. Полезно в тех случаях, когда вы не хотите обрабатывать прослушивание событий и обновление свойства value для сохранения состояния управления в синхронизации.

disableFullscreenUI

Android

Когда false, если доступно мало места вокруг поля ввода (например, в альбомной ориентации на телефоне), ОС может предложить пользователю редактировать текст в режиме полноэкранного поля ввода. Когда true, эта функция отключена, и пользователи всегда будут редактировать текст непосредственно в поле ввода. По умолчанию false.

editable

Если false, текст не редактируется. Значение по умолчанию true.

enablesReturnKeyAutomatically

iOS

Если true, клавиатура отключает клавишу возврата, когда нет текста, и автоматически включает ее, когда текст есть. Значение по умолчанию false.

importantForAutofill

Android

Указывает операционной системе, следует ли включать отдельные поля в структуру отображения для целей автозаполнения на Android API Level 26+. Возможные значения: auto, no, noExcludeDescendants, yes, и yesExcludeDescendants. Значение по умолчанию auto.

• auto: Позволяет системе Android использовать свои эвристики для определения, важно ли это представление для автозаполнения.
• no: Это представление не важно для автозаполнения.
• noExcludeDescendants: Это представление и его дочерние элементы не важны для автозаполнения.
• yes: Это представление важно для автозаполнения.
• yesExcludeDescendants: Это представление важно для автозаполнения, но его дочерние элементы не важны для автозаполнения.

inlineImageLeft

Android

Если определено, предоставленное изображение ресурса будет отображаться слева. Ресурс изображения должен быть внутри /android/app/src/main/res/drawable и ссылаться так

<TextInput
 inlineImageLeft='search_icon'
/>

inlineImagePadding

Android

Отступ между встроенным изображением (если есть) и самим текстовым полем.

inputAccessoryViewID

iOS

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

keyboardAppearance

iOS

Определяет цвет клавиатуры.

keyboardType

Определяет, какая клавиатура должна открыться, например, numeric.

См. скриншоты всех типов здесь.

Следующие значения работают на всех платформах:

• default
• number-pad
• decimal-pad
• numeric
• email-address
• phone-pad
• url

Только для iOS

Следующие значения работают только на iOS:

• ascii-capable
• numbers-and-punctuation
• name-phone-pad
• twitter
• web-search

Только для Android

Следующие значения работают только на Android:

• visible-password

maxFontSizeMultiplier

Устанавливает максимальный возможный масштаб шрифта, когда allowFontScaling включен. Возможные значения:

• null/undefined (по умолчанию): наследуется от родительского узла или от глобального значения по умолчанию (0)
• 0: нет ограничения, игнорируется родительский/глобальный параметр по умолчанию
• >= 1: устанавливает maxFontSizeMultiplier этого узла в это значение

maxLength

Ограничивает максимальное количество символов, которые можно ввести. Используйте это вместо реализации логики в JS, чтобы избежать мерцания.

multiline

Если true, текстовое поле может содержать несколько строк. Значение по умолчанию - false.

Примечание:

Важно отметить, что это выравнивает текст по верху на iOS и по центру на Android. Используйте с textAlignVertical , установленным на top, для одинакового поведения на обеих платформах.

numberOfLines

Android

Устанавливает количество строк для TextInput. Используйте его с multiline, установленным на true, чтобы заполнить строки.

onBlur

Обработчик, вызываемый, когда текстовое поле теряет фокус.

Примечание: Если вы пытаетесь получить доступ к значению text из nativeEvent, помните, что полученное значение может быть undefined, что может привести к непредвиденным ошибкам. Если вы пытаетесь найти последнее значение TextInput, используйте событие onEndEditing, которое срабатывает по завершении редактирования.

onChange

Обработчик, вызываемый при изменении текста в текстовом поле.

onChangeText

Обработчик, вызываемый при изменении текста в текстовом поле. Измененный текст передается как единственный строковый аргумент в обработчик.

onContentSizeChange

Обработчик, вызываемый при изменении размера содержимого текстового поля.

Вызывается только для многострочных текстовых полей.

onEndEditing

Обработчик, вызываемый при завершении редактирования текстового поля.

onPressIn

Обработчик, вызываемый при нажатии.

onPressOut

Обработчик, вызываемый при отпускании.

onFocus

Обработчик, вызываемый при получении фокуса текстовым полем.

onKeyPress

Обработчик, вызываемый при нажатии клавиши. Будет вызван с объектом, где keyValue равно 'Enter' или 'Backspace' для соответствующих клавиш и набранным символом в противном случае, включая ' ' для пробела. Вызывается до onChange обработчиков. Примечание: на Android обрабатываются только ввод с виртуальной клавиатуры, а не ввод с физической клавиатуры.

onLayout

Вызывается при монтировании и при изменениях макета.

onScroll

Вызывается при прокрутке содержимого. Может также содержать другие свойства из ScrollEvent, но на Android contentSize не предоставляется по соображениям производительности.

onSelectionChange

Обработчик, вызываемый при изменении выделения текста в текстовом поле.

onSubmitEditing

Обработчик, вызываемый при нажатии кнопки отправки в текстовом поле.

Обратите внимание, что на iOS этот метод не вызывается при использовании keyboardType="phone-pad".

placeholder

Строка, которая будет отображаться перед вводом текста.

placeholderTextColor

Цвет текста подсказки.

returnKeyLabel

Android

Устанавливает метку для клавиши возврата. Используйте вместо returnKeyType.

returnKeyType

Определяет, как должна выглядеть клавиша возврата. На Android также можно использовать returnKeyLabel.

На всех платформах

Следующие значения работают на всех платформах:

• done
• go
• next
• search
• send

Только для Android

Следующие значения работают только на Android:

• none
• previous

Только для iOS

Следующие значения работают только на iOS:

• default
• emergency-call
• google
• join
• route
• yahoo

rejectResponderTermination

iOS

Если true, разрешает TextInput передавать события касания родительскому компоненту. Это позволяет компонентам, таким как SwipeableListView, быть прокручиваемыми через TextInput на iOS, как это по умолчанию на Android. Если false, TextInput всегда запрашивает обработку ввода (кроме случаев отключения). Значение по умолчанию - true.

scrollEnabled

iOS

Если false, прокрутка текстового поля будет отключена. Значение по умолчанию - true. Работает только с multiline={true}.

secureTextEntry

Если true, текстовое поле скрывает введенный текст, чтобы чувствительная информация, например, пароли, оставалась защищенной. Значение по умолчанию - false. Не работает с multiline={true}.

selection

Начало и конец выделения в текстовом поле. Установите начало и конец в одно и то же значение, чтобы установить курсор.

selectionColor

Цвет выделения и курсора текстового поля.

selectTextOnFocus

Если true, весь текст будет автоматически выделен при получении фокуса.

showSoftInputOnFocus

Когда false, это предотвратит отображение виртуальной клавиатуры при фокусировке на поле. Значение по умолчанию — true.

spellCheck

iOS

Если false, отключает стиль проверки правописания (т.е. красные подчеркивания). Значение по умолчанию наследуется от autoCorrect.

textAlign

Выравнивание вводимого текста по левому, центру или правому краю поля ввода.

Возможные значения для textAlign:

• left
• center
• right

textContentType

iOS

Предоставление клавиатуре и системе информации о предполагаемом семантическом значении вводимого пользователем контента.

Для iOS 11+ вы можете установить textContentType на username или password для активации автозаполнения данных входа с ключа устройства.

Для iOS 12+ newPassword можно использовать для обозначения нового пароля, который пользователь может сохранить в keychain, а oneTimeCode можно использовать для указания того, что поле может быть автоматически заполнено кодом, пришедшим в SMS.

Для отключения автозаполнения установите textContentType на none.

Возможные значения для textContentType:

• none
• URL
• addressCity
• addressCityAndState
• addressState
• countryName
• creditCardNumber
• emailAddress
• familyName
• fullStreetAddress
• givenName
• jobTitle
• location
• middleName
• name
• namePrefix
• nameSuffix
• nickname
• organizationName
• postalCode
• streetAddressLine1
• streetAddressLine2
• sublocality
• telephoneNumber
• username
• password
• newPassword
• oneTimeCode

passwordRules

iOS

При использовании textContentType в качестве newPassword на iOS, мы можем сообщить ОС о минимальных требованиях к паролю, чтобы она могла сгенерировать пароль, соответствующий этим требованиям. Чтобы создать корректную строку для PasswordRules, обратитесь к Документации Apple.

Если диалоговое окно для генерации паролей не появляется, убедитесь в следующем:

• Автозаполнение включено: Настройки → Пароли и учётные записи → включить Автозаполнение паролей,
• Используется iCloud Keychain: Настройки → Apple ID → iCloud → Keychain → включить iCloud Keychain.

style

Обратите внимание, что не все стили текста поддерживаются. Неподдерживаемые стили включают, но не ограничиваются:

• borderLeftWidth
• borderTopWidth
• borderRightWidth
• borderBottomWidth
• borderTopLeftRadius
• borderTopRightRadius
• borderBottomRightRadius
• borderBottomLeftRadius

Дополнительную информацию см. в Проблеме #7070.

Стили

textBreakStrategy

Android

Установите стратегию разбиения текста на Android API Level 23+, возможные значения — simple, highQuality, balanced Значение по умолчанию — simple.

underlineColorAndroid

Android

Цвет подчеркивания TextInput.

value

Значение, отображаемое для текстового поля ввода. TextInput — компонент с управлением, что означает, что значение нативного компонента будет принудительно соответствовать значению этого свойства, если оно предоставлено. Для большинства случаев это отлично работает, но в некоторых случаях это может привести к мерцанию — одной из распространённых причин является предотвращение редактирования, сохраняя значение неизменным. В дополнение к установке одинакового значения, установите editable={false}, или установите/обновите maxLength, чтобы предотвратить нежелательные изменения без мерцания.

Methods

.focus()

focus();

Запрашивает фокус у нативного поля ввода.

.blur()

blur();

Убирает фокус у нативного поля ввода.

clear()

clear();

Удаляет весь текст из TextInput.

isFocused()

isFocused();

Возвращает true, если поле ввода имеет фокус; false, в противном случае.

Известные проблемы

• react-native#19096: Не поддерживает onKeyPreIme Android.
• react-native#19366: Вызов .focus() после закрытия клавиатуры Android через кнопку «Назад» не вызывает повторное отображение клавиатуры.
• react-native#26799: Не поддерживает secureTextEntry Android, когда keyboardType="email-address" или keyboardType="phone-pad".