跳到主要内容
版本：0.81

TextInput

一个用于通过键盘向应用输入文本的基础组件。Props 提供了多项功能的配置能力，例如自动纠正、自动大写、占位文本以及不同的键盘类型，例如数字键盘。

最基本的用法是放置一个 TextInput，并订阅 onChangeText 事件来读取用户输入。还可以订阅其他事件，例如 onSubmitEditing 和 onFocus。一个最小示例：

原生元素提供了两个方法：.focus() 和 .blur()，可用于以编程方式让 TextInput 获得或失去焦点。

请注意，某些 props 仅在 multiline={true/false} 时可用：

TextInput 默认会在其视图底部显示边框。此边框的内边距由系统提供的背景图像设置，无法更改。要避免这种情况，可以不显式设置高度，此时系统会负责在正确的位置显示边框；或者将 underlineColorAndroid 设置为透明，以不显示边框。

请注意，在 Android 上对输入框中的文本执行选择操作，可能会将应用的 activity windowSoftInputMode 参数更改为 adjustResize。这可能会导致键盘处于活动状态时，使用 position: 'absolute' 的组件出现问题。要避免此行为，可以在 AndroidManifest.xml（ https://developer.android.com/guide/topics/manifest/activity-element.html ）中指定 windowSoftInputMode，或者使用原生代码以编程方式控制此参数。

参考

Props​

View Props​

继承 View Props。

allowFontScaling​

指定字体是否应进行缩放，以遵循辅助功能中的文本大小设置。默认值为 true。

类型
bool

autoCapitalize​

告知 TextInput 自动将某些字符大写。某些键盘类型不支持此属性，例如 name-phone-pad。

  • characters：所有字符。
  • words：每个单词的首字母。
  • sentences：每个句子的首字母（默认）。
  • none：不自动将任何内容大写。
类型
enum('none', 'sentences', 'words', 'characters')

autoComplete​

为系统指定自动完成提示，以便系统提供自动填充。在 Android 上，系统始终会尝试使用启发式方法识别内容类型来提供自动填充。要禁用自动完成，请将 autoComplete 设置为 off。

以下值适用于所有平台：

  • additional-name
  • address-line1
  • address-line2
  • birthdate-day（iOS 17+）
  • birthdate-full（iOS 17+）
  • birthdate-month（iOS 17+）
  • birthdate-year（iOS 17+）
  • cc-csc（iOS 17+）
  • cc-exp（iOS 17+）
  • cc-exp-day（iOS 17+）
  • cc-exp-month（iOS 17+）
  • cc-exp-year（iOS 17+）
  • cc-number
  • country
  • current-password
  • email
  • family-name
  • given-name
  • honorific-prefix
  • honorific-suffix
  • name
  • new-password
  • off
  • one-time-code
  • postal-code
  • street-address
  • tel
  • username
iOS

以下值仅适用于 iOS：

  • cc-family-name（iOS 17+）
  • cc-given-name（iOS 17+）
  • cc-middle-name（iOS 17+）
  • cc-name（iOS 17+）
  • cc-type（iOS 17+）
  • nickname
  • organization
  • organization-title
  • url
Android

以下值仅适用于 Android：

  • gender
  • 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
  • sms-otp
  • tel-country-code
  • tel-device
  • tel-national
  • username-new
类型
enum('additional-name', 'address-line1', 'address-line2', 'birthdate-day', 'birthdate-full', 'birthdate-month', 'birthdate-year', 'cc-csc', 'cc-exp', 'cc-exp-day', 'cc-exp-month', 'cc-exp-year', 'cc-number', 'country', 'current-password', 'email', 'family-name', 'given-name', 'honorific-prefix', 'honorific-suffix', 'name', 'new-password', 'off', 'one-time-code', 'postal-code', 'street-address', 'tel', 'username', 'cc-family-name', 'cc-given-name', 'cc-middle-name', 'cc-name', 'cc-type', 'nickname', 'organization', 'organization-title', 'url', 'gender', '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', 'sms-otp', 'tel-country-code', 'tel-device', 'tel-national', 'username-new')

autoCorrect​

如果为 false，则禁用自动纠正。默认值为 true。

类型
bool

autoFocus​

如果为 true，则让输入框获得焦点。默认值为 false。

类型
bool

blurOnSubmit​

已弃用。 请注意，submitBehavior 现在取代了 blurOnSubmit，并会覆盖由 blurOnSubmit 定义的任何行为。请参阅 submitBehavior

如果为 true，文本字段将在提交时失去焦点。对于单行字段，默认值为 true；对于多行字段，默认值为 false。请注意，对于多行字段，将 blurOnSubmit 设置为 true 表示按下回车键会使字段失去焦点，并触发 onSubmitEditing 事件，而不是在字段中插入换行符。

类型
bool

caretHidden​

如果为 true，则隐藏插入符。默认值为 false。

类型
bool

clearButtonMode
iOS
​

指定清除按钮应在文本视图右侧何时出现。此属性仅支持单行 TextInput 组件。默认值为 never。

类型
enum('never', 'while-editing', 'unless-editing', 'always')

clearTextOnFocus
iOS
​

如果为 true，则在开始编辑时自动清除文本字段。

类型
bool

contextMenuHidden​

如果为 true，则隐藏上下文菜单。默认值为 false。

类型
bool

dataDetectorTypes
iOS
​

确定文本输入中转换为可点击 URL 的数据类型。仅当 multiline={true} 且 editable={false} 时有效。默认情况下不会检测任何数据类型。

可以提供一种类型，也可以提供包含多种类型的数组。

dataDetectorTypes 的可能值包括：

  • 'phoneNumber'
  • 'link'
  • 'address'
  • 'calendarEvent'
  • 'none'
  • 'all'
类型
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all')

defaultValue​

提供一个初始值，该值会在用户开始输入时发生变化。适用于不想处理监听事件并更新 value prop 来保持受控状态同步的场景。

类型
string

方法​

.focus()​

React TSX
focus();

使原生输入框请求焦点。

.blur()​

React TSX
blur();

使原生输入框失去焦点。

clear()​

React TSX
clear();

移除 TextInput 中的所有文本。

isFocused()​

React TSX
isFocused(): boolean;

如果输入框当前已获得焦点，则返回 true；否则返回 false。

已知问题

  • react-native#19096：不支持 Android 的 onKeyPreIme。
  • react-native#19366：通过返回键关闭 Android 键盘后再调用 .focus()，不会再次弹出键盘。
  • react-native#26799：当 keyboardType="email-address" 或 keyboardType="phone-pad" 时，不支持 Android 的 secureTextEntry。