TextInput

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

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

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

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

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

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

参考

属性

View 属性

继承自 View 属性。

`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')

类型

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，则在componentDidMount或useEffect中聚焦输入。默认值为false。

类型
bool

`blurOnSubmit`

如果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 属性以使受控状态保持同步的用例很有用。

类型
string

`cursorColor`
Android

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

类型
color

`disableFullscreenUI`
Android

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

类型
bool

`editable`

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

类型
bool

`enablesReturnKeyAutomatically`
iOS

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

类型
bool

`enterKeyHint`

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

以下值跨平台有效

enter
done
next
search
send

仅限 Android

以下值仅在 Android 上有效

previous

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

`importantForAutofill`
Android

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

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

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

`inlineImageLeft`
Android

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

<TextInput
 inlineImageLeft='search_icon'
/>

类型
string

`inlineImagePadding`
Android

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

类型
number

`inputAccessoryViewID`
iOS

一个可选的标识符，它将自定义的InputAccessoryView链接到此文本输入。当此文本输入获得焦点时，InputAccessoryView 会渲染在键盘上方。

类型
string

`inputMode`

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

支持以下值

none
text
decimal
numeric
tel
search
email
url

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

`keyboardAppearance`
iOS

确定键盘的颜色。

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

`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

类型
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 设置为该值。

类型
number

`maxLength`

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

类型
number

`multiline`

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

注意

需要注意的是，这会将文本在 iOS 上对齐到顶部，在 Android 上居中。与设置为 top 的 textAlignVertical 一起使用，以便在两个平台上获得相同的效果。

类型
bool

`numberOfLines`
Android

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

类型
number

`onBlur`

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

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

类型
函数

`onChange`

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

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

`onChangeText`

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

类型
函数

`onContentSizeChange`

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

仅对多行文本输入调用。

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

`onEndEditing`

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

类型
函数

`onPressIn`

触摸开始时调用的回调函数。

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

`onPressOut`

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

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

`onFocus`

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

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

`onKeyPress`

按下键时调用的回调函数。它将使用一个对象调用，其中 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`

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

类型
string

`placeholderTextColor`

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

类型
color

`readOnly`

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

类型
bool

`returnKeyLabel`
Android

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

类型
string

`returnKeyType`

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

跨平台

以下值跨平台有效

done
go
next
search
send

仅限 Android

以下值仅在 Android 上有效

none
previous

仅限 iOS

以下值仅在 iOS 上有效

default
emergency-call
google
join
route
yahoo

类型
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。

类型
bool

`rows`
Android

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

类型
number

`scrollEnabled`
iOS

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

类型
bool

`secureTextEntry`

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

类型
bool

`selection`

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

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

`selectionColor`

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

类型
color

`selectionHandleColor`
Android

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

类型
color

`selectTextOnFocus`

如果为 true，则所有文本将在获得焦点时自动被选中。

类型
bool

`showSoftInputOnFocus`

当为 false 时，它将阻止软键盘在字段获得焦点时显示。默认值为 true。

类型
bool

`spellCheck`
iOS

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

类型
bool

`textAlign`

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

textAlign 的可能值为

left
center
right

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

`textContentType`
iOS

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

注意

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

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

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

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

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

textContentType 的可能值为

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

类型

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 钥匙串** 切换为“开启”。

类型
string

`style`

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

borderLeftWidth
borderTopWidth
borderRightWidth
borderBottomWidth
borderTopLeftRadius
borderTopRightRadius
borderBottomRightRadius
borderBottomLeftRadius

样式

类型
Text

`textBreakStrategy`
Android

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

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

`underlineColorAndroid`
Android

TextInput 下划线的颜色。

类型
color

`value`

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

类型
string

`lineBreakStrategyIOS`
iOS

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

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

方法

`.focus()`

focus();

使本机输入请求焦点。

`.blur()`

blur();

使本机输入失去焦点。

`clear()`

clear();

从 TextInput 中删除所有文本。

`isFocused()`

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。

属性
方法

参考

属性​

View 属性​

allowFontScaling​

autoCapitalize​

autoComplete​

autoCorrect​

autoFocus​

blurOnSubmit​

caretHidden​

clearButtonMode iOS​

clearTextOnFocus iOS​

contextMenuHidden​

dataDetectorTypes iOS​

defaultValue​

cursorColor Android​

disableFullscreenUI Android​

editable​

enablesReturnKeyAutomatically iOS​

enterKeyHint​

importantForAutofill Android​

inlineImageLeft Android​

inlineImagePadding Android​

inputAccessoryViewID iOS​

inputMode​

keyboardAppearance iOS​

keyboardType​

maxFontSizeMultiplier​

maxLength​

multiline​

numberOfLines Android​

onBlur​

onChange​

onChangeText​

onContentSizeChange​

onEndEditing​

onPressIn​

onPressOut​

onFocus​

onKeyPress​

onLayout​

onScroll​

onSelectionChange​

onSubmitEditing​

placeholder​

placeholderTextColor​

readOnly​

returnKeyLabel Android​

returnKeyType​

rejectResponderTermination iOS​

rows Android​

scrollEnabled iOS​

secureTextEntry​

selection​

selectionColor​

selectionHandleColor Android​

selectTextOnFocus​

showSoftInputOnFocus​

spellCheck iOS​

textAlign​

textContentType iOS​

passwordRules iOS​

style​

textBreakStrategy Android​

underlineColorAndroid Android​

value​

lineBreakStrategyIOS iOS​

方法​

.focus()​

.blur()​

clear()​

isFocused()​

已知问题

属性

View 属性

`allowFontScaling`

`autoCapitalize`

`autoComplete`

`autoCorrect`

`autoFocus`

`blurOnSubmit`

`caretHidden`

`clearButtonMode`
iOS

`clearTextOnFocus`
iOS

`contextMenuHidden`

`dataDetectorTypes`
iOS

`defaultValue`

`cursorColor`
Android

`disableFullscreenUI`
Android

`editable`

`enablesReturnKeyAutomatically`
iOS

`enterKeyHint`

`importantForAutofill`
Android

`inlineImageLeft`
Android

`inlineImagePadding`
Android

`inputAccessoryViewID`
iOS

`inputMode`

`keyboardAppearance`
iOS

`keyboardType`

`maxFontSizeMultiplier`

`maxLength`

`multiline`

`numberOfLines`
Android

`onBlur`

`onChange`

`onChangeText`

`onContentSizeChange`

`onEndEditing`

`onPressIn`

`onPressOut`

`onFocus`

`onKeyPress`

`onLayout`

`onScroll`

`onSelectionChange`

`onSubmitEditing`

`placeholder`

`placeholderTextColor`

`readOnly`

`returnKeyLabel`
Android

`returnKeyType`

`rejectResponderTermination`
iOS

`rows`
Android

`scrollEnabled`
iOS

`secureTextEntry`

`selection`

`selectionColor`

`selectionHandleColor`
Android

`selectTextOnFocus`

`showSoftInputOnFocus`

`spellCheck`
iOS

`textAlign`

`textContentType`
iOS

`passwordRules`
iOS

`style`

`textBreakStrategy`
Android

`underlineColorAndroid`
Android

`value`

`lineBreakStrategyIOS`
iOS

方法

`.focus()`

`.blur()`

`clear()`

`isFocused()`