文本输入

通过键盘在应用程序中输入文本的基础组件。属性提供了多种功能的可配置性，例如自动更正、自动大写、占位符文本以及不同类型的键盘，例如数字键盘。

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

通过原生元素公开的两个方法是 .focus() 和 .blur()，它们将以编程方式聚焦或失焦 TextInput。

请注意，某些属性仅在使用 multiline={true/false} 时可用。此外，如果 multiline=true，则仅适用于元素一侧的边框样式（例如 borderBottomColor、borderLeftWidth 等）将不适用。要实现相同的效果，您可以将 TextInput 包装在 View 中

TextInput 默认在其视图底部有一个边框。此边框的填充由系统提供的背景图像设置，无法更改。避免这种情况的解决方案是，要么不显式设置高度，在这种情况下系统将负责在正确位置显示边框，要么通过将 underlineColorAndroid 设置为透明来不显示边框。

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

---

参考

属性

View 属性

继承自 View 属性。

---

allowFontScaling

指定字体是否应按文本大小可访问性设置进行缩放。默认值为 true。

类型
布尔值

---

autoCapitalize

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

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

类型
enum('none', 'sentences', 'words', 'characters')

---

autoComplete

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

以下值适用于所有平台

• 附加名称
• 地址行1
• 地址行2
• 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+)
• 信用卡号码
• 国家/地区
• 当前密码
• 电子邮件
• 姓氏
• 名字
• 尊称前缀
• 尊称后缀
• 名称
• 新密码
• 关闭
• 一次性代码
• 邮政编码
• 街道地址
• 电话
• 用户名

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+)
• 昵称
• 组织
• 组织名称
• 网址

安卓

以下值仅适用于 Android

• 性别
• 姓名-姓氏
• 姓名-名字
• 姓名-中间名
• 姓名-中间名首字母
• 姓名-前缀
• 姓名-后缀
• 密码
• 新密码
• 邮政地址
• 邮政地址-国家
• 邮政地址-扩展
• 邮政地址-扩展邮政编码
• 邮政地址-地区
• 邮政地址-省/自治区
• 短信验证码
• 电话-国家代码
• 电话-设备
• 电话-国内
• 新用户名

类型

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。

类型
布尔值

---

autoFocus

如果为 true，则聚焦输入。默认值为 false。

类型
布尔值

---

blurOnSubmit

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

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

类型
布尔值

---

caretHidden

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

类型
布尔值

---

clearButtonMode

iOS

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

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

---

clearTextOnFocus

iOS

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

类型
布尔值

---

contextMenuHidden

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

类型
布尔值

---

dataDetectorTypes

iOS

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

您可以提供一种类型或多种类型的数组。

dataDetectorTypes 的可能值为

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

类型
enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') 数组

---

defaultValue

提供一个初始值，该值将在用户开始输入时更改。适用于您不想处理监听事件和更新值属性以保持受控状态同步的情况。

类型
字符串

---

cursorColor

安卓

如果提供，它将设置组件中光标（或“插入符”）的颜色。与 selectionColor 的行为不同，光标颜色将独立于文本选择框的颜色设置。

类型
颜色

---

disableFullscreenUI

安卓

如果为 false，如果文本输入周围可用空间很小（例如手机上的横向），操作系统可能会选择让用户在全屏文本输入模式下编辑文本。如果为 true，则禁用此功能，用户将始终直接在文本输入中编辑文本。默认为 false。

类型
布尔值

---

editable

如果为 false，则文本不可编辑。默认值为 true。

类型
布尔值

---

enablesReturnKeyAutomatically

iOS

如果为 true，则在没有文本时键盘禁用回车键，并在有文本时自动启用。默认值为 false。

类型
布尔值

---

enterKeyHint

确定回车键应显示什么文本。优先于 returnKeyType 属性。

以下值适用于所有平台

• 完成
• 下一步
• 搜索
• 发送
• 前往

仅限安卓

以下值仅适用于 Android

• 上一个

仅限 iOS

以下值仅适用于 iOS

• 回车

类型
enum('enter', 'done', 'next', 'previous', 'search', 'send', 'go')

---

importantForAutofill

安卓

告诉操作系统您的应用程序中的各个字段是否应包含在视图结构中以用于 Android API Level 26+ 上的自动填充目的。可能的值为 auto、no、noExcludeDescendants、yes 和 yesExcludeDescendants。默认值为 auto。

• auto：让 Android 系统使用其启发式方法来确定视图是否对自动填充很重要。
• no：此视图对自动填充不重要。
• noExcludeDescendants：此视图及其子视图对自动填充不重要。
• yes：此视图对自动填充很重要。
• yesExcludeDescendants：此视图对自动填充很重要，但其子视图对自动填充不重要。

类型
enum('auto', 'no', 'noExcludeDescendants', 'yes', 'yesExcludeDescendants')

---

inlineImageLeft

安卓

如果已定义，则提供的图像资源将呈现在左侧。图像资源必须位于 /android/app/src/main/res/drawable 中，并按以下方式引用

<TextInput
 inlineImageLeft='search_icon'
/>

类型
字符串

---

inlineImagePadding

安卓

内联图像（如果有）和文本输入本身之间的填充。

类型
数字

---

inputAccessoryViewID

iOS

一个可选的标识符，将自定义 InputAccessoryView 链接到此文本输入。当此文本输入聚焦时，InputAccessoryView 将呈现在键盘上方。

类型
字符串

---

inputAccessoryViewButtonLabel

iOS

一个可选标签，它覆盖默认的 InputAccessoryView 按钮标签。

默认情况下，默认按钮标签不会本地化。使用此属性提供本地化版本。

类型
字符串

---

inputMode

作用类似于 HTML 中的 inputmode 属性，它决定打开哪个键盘，例如 numeric，并且优先于 keyboardType。

支持以下值

• 无
• 文本
• 十进制
• 数字
• 电话
• 搜索
• 电子邮件
• 网址

类型
enum('decimal', 'email', 'none', 'numeric', 'search', 'tel', 'text', 'url')

---

keyboardAppearance

iOS

确定键盘的颜色。

类型
enum('default', 'light', 'dark')

---

keyboardType

确定打开哪个键盘，例如 numeric。

在此处查看所有类型的截图 这里。

以下值适用于所有平台

• 默认
• 数字键盘
• 十进制键盘
• 数字
• 电子邮件地址
• 电话键盘
• 网址

仅限 iOS

以下值仅适用于 iOS

• ASCII 字符
• 数字和标点符号
• 名称-电话键盘
• Twitter
• 网页搜索

仅限安卓

以下值仅适用于 Android

• 可见密码

类型
enum('default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter', 'web-search', 'visible-password')

---

maxFontSizeMultiplier

指定启用 allowFontScaling 时字体可以达到的最大可能缩放比例。可能的值

• null/undefined (默认)：继承自父节点或全局默认值 (0)
• 0：无最大值，忽略父/全局默认值
• >= 1：将此节点的 maxFontSizeMultiplier 设置为此值

类型
数字

---

maxLength

限制可以输入的字符的最大数量。使用此方法而不是在 JS 中实现逻辑，以避免闪烁。

类型
数字

---

multiline

如果为 true，则文本输入可以是多行。默认值为 false。

注意

需要注意的是，这在 iOS 上会将文本对齐到顶部，在 Android 上则居中。将 textAlignVertical 设置为 top 以在两个平台中实现相同的行为。

类型
布尔值

---

numberOfLines

注意

iOS 上的 numberOfLines 仅在 新架构 中可用

设置 TextInput 的最大行数。与 multiline 设置为 true 一起使用才能填充行。

类型
数字

---

onBlur

当文本输入框失去焦点时调用的回调函数。

注意：如果您尝试从 nativeEvent 访问 text 值，请记住您获得的结果值可能是 undefined，这可能会导致意外错误。如果您试图查找 TextInput 的最后一个值，您可以使用 onEndEditing 事件，该事件在编辑完成后触发。

类型
({nativeEvent: TargetEvent}) => void

---

onChange

当文本输入框的文本更改时调用的回调函数。

类型
({nativeEvent: {eventCount, target, text}}) => void

---

onChangeText

当文本输入框的文本更改时调用的回调函数。更改后的文本作为单个字符串参数传递给回调处理程序。

类型
函数

---

onContentSizeChange

当文本输入框的内容大小更改时调用的回调函数。

仅适用于多行文本输入框。

类型
({nativeEvent: {contentSize: {width, height} }}) => void

---

onEndEditing

文本输入结束时调用的回调函数。

类型
函数

---

onPressIn

触摸按下时调用的回调函数。

类型
({nativeEvent: PressEvent}) => void

---

onPressOut

触摸释放时调用的回调函数。

类型
({nativeEvent: PressEvent}) => void

---

onFocus

当文本输入框获得焦点时调用的回调函数。

类型
({nativeEvent: TargetEvent}) => void

---

onKeyPress

按下键时调用的回调函数。此函数将使用包含 keyValue 的对象调用，其中 keyValue 对于相应的键是 'Enter' 或 'Backspace'，否则是输入的字符，包括空格符 ' '。在 onChange 回调之前触发。注意：在 Android 上，只处理软键盘的输入，不处理硬件键盘的输入。

类型
({nativeEvent: {key: keyValue} }) => void

---

onLayout

在挂载和布局更改时调用。

类型
({nativeEvent: LayoutEvent}) => void

---

onScroll

在内容滚动时调用。也可能包含 ScrollEvent 中的其他属性，但出于性能原因，Android 上不提供 contentSize。

类型
({nativeEvent: {contentOffset: {x, y} }}) => void

---

onSelectionChange

当文本输入框选择发生变化时调用的回调函数。

类型
({nativeEvent: {selection: {start, end} }}) => void

---

onSubmitEditing

当文本输入框的提交按钮被按下时调用的回调函数。

类型
({nativeEvent: {text, eventCount, target}}) => void

请注意，在 iOS 上使用 keyboardType="phone-pad" 时不调用此方法。

---

placeholder

在输入文本之前将呈现的字符串。

类型
字符串

---

placeholderTextColor

占位符字符串的文本颜色。

类型
颜色

---

readOnly

如果为 true，则文本不可编辑。默认值为 false。

类型
布尔值

---

returnKeyLabel

安卓

将回车键设置为标签。使用它而不是 returnKeyType。

类型
字符串

---

returnKeyType

确定回车键的外观。在 Android 上，您还可以使用 returnKeyLabel。

跨平台

以下值适用于所有平台

• 完成
• 前往
• 下一步
• 搜索
• 发送

仅限安卓

以下值仅适用于 Android

• 无
• 上一个

仅限 iOS

以下值仅适用于 iOS

• 默认
• 紧急呼叫
• 谷歌
• 加入
• 路线
• 雅虎

类型
enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo')

rejectResponderTermination

iOS

如果为 true，则允许 TextInput 将触摸事件传递给父组件。这使得 SwipeableListView 等组件可以在 iOS 上从 TextInput 滑动，就像 Android 上默认情况一样。如果为 false，TextInput 总是要求处理输入（禁用时除外）。默认值为 true。

类型
布尔值

---

rows

安卓

设置 TextInput 的行数。与 multiline 设置为 true 一起使用才能填充行。

类型
数字

---

scrollEnabled

iOS

如果为 false，则文本视图的滚动将被禁用。默认值为 true。仅适用于 multiline={true}。

类型
布尔值

---

secureTextEntry

如果为 true，则文本输入会模糊输入的文本，以便密码等敏感文本保持安全。默认值为 false。不适用于 multiline={true}。

类型
布尔值

---

selection

文本输入框选择的开始和结束。将开始和结束设置为相同的值以定位光标。

类型
对象：{start: number,end: number}

---

selectionColor

文本输入框的突出显示、选择手柄和光标颜色。

类型
颜色

---

selectionHandleColor

安卓

设置选择手柄的颜色。与 selectionColor 不同，它允许选择手柄颜色独立于选择颜色进行自定义。

类型
颜色

---

selectTextOnFocus

如果为 true，则在聚焦时会自动选择所有文本。

类型
布尔值

---

showSoftInputOnFocus

如果为 false，则当字段聚焦时，它将阻止软键盘显示。默认值为 true。

类型
布尔值

---

spellCheck

iOS

如果为 false，则禁用拼写检查样式（即红色下划线）。默认值继承自 autoCorrect。

类型
布尔值

---

submitBehavior

当按下回车键时，

对于单行输入

• 'newline' 默认为 'blurAndSubmit'
• undefined 默认为 'blurAndSubmit'

对于多行输入

• 'newline' 添加新行
• undefined 默认为 'newline'

对于单行和多行输入

• 'submit' 将只发送提交事件，而不使输入失去焦点
• 'blurAndSubmit' 将同时使输入失去焦点并发送提交事件

类型
enum('submit', 'blurAndSubmit', 'newline')

---

textAlign

将输入文本对齐到输入字段的左侧、中心或右侧。

textAlign 的可能值为

• 左对齐
• 居中
• 右对齐

类型
enum('left', 'center', 'right')

---

textContentType

iOS

向键盘和系统提供有关用户输入内容预期语义含义的信息。

注意

autoComplete 提供了相同的功能，并且适用于所有平台。您可以使用 Platform.select 来实现不同的平台行为。

避免同时使用 textContentType 和 autoComplete。为了向后兼容，当同时设置这两个属性时，textContentType 优先。

您可以将 textContentType 设置为 username 或 password 以启用从设备钥匙串自动填充登录详细信息。

newPassword 可用于指示用户可能希望保存在钥匙串中的新密码输入，而 oneTimeCode 可用于指示字段可以通过 SMS 收到的代码自动填充。

要禁用自动填充，请将 textContentType 设置为 none。

textContentType 的可能值为

• 无
• 地址城市
• 地址城市和州
• 地址州
• birthdate (iOS 17+)
• birthdateDay (iOS 17+)
• birthdateMonth (iOS 17+)
• birthdateYear (iOS 17+)
• 国家名称
• creditCardExpiration (iOS 17+)
• creditCardExpirationMonth (iOS 17+)
• creditCardExpirationYear (iOS 17+)
• creditCardFamilyName (iOS 17+)
• creditCardGivenName (iOS 17+)
• creditCardMiddleName (iOS 17+)
• creditCardName (iOS 17+)
• 信用卡号
• creditCardSecurityCode (iOS 17+)
• creditCardType (iOS 17+)
• 电子邮件地址
• 姓氏
• 完整街道地址
• 名字
• 职位
• 位置
• 中间名
• 名称
• 姓名前缀
• 姓名后缀
• 新密码
• 昵称
• 一次性代码
• 组织名称
• 密码
• 邮政编码
• 街道地址行1
• 街道地址行2
• 次级区域
• 电话号码
• URL
• 用户名

类型

enum('none', 'addressCity', 'addressCityAndState', 'addressState', 'birthdate', 'birthdateDay', 'birthdateMonth', 'birthdateYear', 'countryName', 'creditCardExpiration', 'creditCardExpirationMonth', 'creditCardExpirationYear', 'creditCardFamilyName', 'creditCardGivenName', 'creditCardMiddleName', 'creditCardName', 'creditCardNumber', 'creditCardSecurityCode', 'creditCardType', 'emailAddress', 'familyName', 'fullStreetAddress', 'givenName', 'jobTitle', 'location', 'middleName', 'name', 'namePrefix', 'nameSuffix', 'newPassword', 'nickname', 'oneTimeCode', 'organizationName', 'password', 'postalCode', 'streetAddressLine1', 'streetAddressLine2', 'sublocality', 'telephoneNumber', 'URL', 'username')

---

passwordRules

iOS

在 iOS 上使用 textContentType 作为 newPassword 时，我们可以让操作系统知道密码的最低要求，以便它能够生成满足这些要求的密码。要为 PasswordRules 创建有效字符串，请查看 Apple 文档。

如果密码生成对话框未出现，请确保

• 自动填充已启用：设置 → 密码与帐户 → 切换“打开”自动填充密码，
• 使用 iCloud 钥匙串：设置 → Apple ID → iCloud → 钥匙串 → 切换“打开”iCloud 钥匙串。

类型
字符串

---

style

请注意，并非所有文本样式都受支持，不支持的列表不完整，包括

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

样式

类型
文本

---

textBreakStrategy

安卓

在 Android API Level 23+ 上设置文本换行策略，可能的值为 simple、highQuality、balanced。默认值为 highQuality。

类型
enum('simple', 'highQuality', 'balanced')

---

underlineColorAndroid

安卓

TextInput 下划线的颜色。

类型
颜色

---

value

要显示的文本输入值。TextInput 是一个受控组件，这意味着如果提供了此值属性，原生值将被强制匹配此值属性。对于大多数用途，这效果很好，但在某些情况下这可能会导致闪烁 - 一个常见的原因是通过保持值不变来阻止编辑。除了设置相同的值之外，还可以设置 editable={false}，或设置/更新 maxLength 以防止不必要的编辑而无闪烁。

类型
字符串

---

lineBreakStrategyIOS

iOS

在 iOS 14+ 上设置换行策略。可能的值为 none、standard、hangul-word 和 push-out。

类型	默认
enum('none', 'standard', 'hangul-word', 'push-out')	'none'

---

lineBreakModeIOS

iOS

在 iOS 上设置换行模式。可能的值为 wordWrapping、char、clip、head、middle 和 tail。

类型	默认
enum('wordWrapping', 'char', 'clip', 'head', 'middle', 'tail')	'wordWrapping'

---

disableKeyboardShortcuts

iOS

如果为 true，则禁用键盘快捷键（撤消/重做和复制按钮）。默认值为 false。

类型
布尔值

方法

.focus()

tsx

focus();

使原生输入请求焦点。

.blur()

tsx

blur();

使原生输入失去焦点。

clear()

tsx

clear();

从 TextInput 中删除所有文本。

---

isFocused()

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。