TextInput
一个基础组件,用于通过键盘向应用输入文本。Props 提供了对多种功能的可配置性,例如自动更正、自动大写、占位符文本和不同的键盘类型,例如数字键盘。
最基本的用例是放置一个 TextInput
并订阅 onChangeText
事件以读取用户输入。还有其他事件,例如 onSubmitEditing
和 onFocus
可以订阅。一个最小的例子
通过原生元素公开的两个方法是 .focus()
和 .blur()
,它们将以编程方式聚焦或失焦 TextInput。
请注意,某些 props 仅在 multiline={true/false}
的情况下可用。此外,如果 multiline=true
,则仅应用于元素一侧的边框样式(例如,borderBottomColor
、borderLeftWidth
等)将不会被应用。要实现相同的效果,您可以将 TextInput
包装在 View
中
TextInput
默认在其视图底部有一个边框。此边框的内边距由系统提供的背景图像设置,并且无法更改。避免这种情况的解决方案是不显式设置高度,在这种情况下,系统将负责在正确的位置显示边框,或者通过将 underlineColorAndroid
设置为 transparent 来不显示边框。
请注意,在 Android 上,在输入框中执行文本选择可能会将应用程序的 activity windowSoftInputMode
参数更改为 adjustResize
。这可能会导致当键盘处于活动状态时,具有 position: 'absolute' 的组件出现问题。要避免此行为,请在 AndroidManifest.xml 中指定 windowSoftInputMode
(https://developer.android.com.cn/guide/topics/manifest/activity-element.html)或使用原生代码以编程方式控制此参数。
参考
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 上有效
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 上有效
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 |
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 Level 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
。
请在此处查看所有类型的屏幕截图 here。
以下值跨平台通用
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 上将其居中对齐。将 textAlignVertical
设置为 top
以在两个平台上获得相同的行为。
类型 |
---|
bool |
numberOfLines
Android
设置 TextInput
的行数。将其与设置为 true
的 multiline 一起使用,以便能够填充行。
类型 |
---|
number |
onBlur
当文本输入失焦时调用的回调。
注意:如果您尝试从
nativeEvent
访问text
值,请记住您获得的最终值可能是undefined
,这可能会导致意外错误。如果您尝试查找 TextInput 的最后一个值,则可以使用onEndEditing
事件,该事件在编辑完成时触发。
类型 |
---|
function |
onChange
当文本输入的文本更改时调用的回调。
类型 |
---|
({nativeEvent: {eventCount, target, text}} ) => void |
onChangeText
当文本输入的文本更改时调用的回调。更改后的文本作为单个字符串参数传递给回调处理程序。
类型 |
---|
function |
onContentSizeChange
当文本输入的内容大小更改时调用的回调。
仅为多行文本输入调用。
类型 |
---|
({nativeEvent: {contentSize: {width, height} }} ) => void |
onEndEditing
当文本输入结束时调用的回调。
类型 |
---|
function |
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 和 end 设置为相同的值以定位光标。
类型 |
---|
object: {start: number,end: number} |
selectionColor
文本输入的高亮显示、选择句柄和光标颜色。
类型 |
---|
color |
selectionHandleColor
Android
设置选择句柄的颜色。与 selectionColor
不同,它允许独立于选择颜色自定义选择句柄颜色。
类型 |
---|
color |
selectTextOnFocus
如果为 true
,则所有文本将在获得焦点时自动被选中。
类型 |
---|
bool |
showSoftInputOnFocus
当 false
时,它将阻止在字段获得焦点时显示软键盘。默认值为 true
。
类型 |
---|
bool |
spellCheck
iOS
如果为 false
,则禁用拼写检查样式(即红色下划线)。默认值继承自 autoCorrect
。
类型 |
---|
bool |
submitBehavior
当按下返回键时,
对于单行输入
'newline'
默认为'blurAndSubmit'
undefined
默认为'blurAndSubmit'
对于多行输入
'newline'
添加换行符undefined
默认为'newline'
对于单行和多行输入
'submit'
将仅发送提交事件,而不会使输入失焦'blurAndSubmit
' 将使输入失焦并发送提交事件
类型 |
---|
enum('submit', 'blurAndSubmit', 'newline') |
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
请注意,并非所有 Text 样式都受支持,不受支持的不完整列表包括
borderLeftWidth
borderTopWidth
borderRightWidth
borderBottomWidth
borderTopLeftRadius
borderTopRightRadius
borderBottomRightRadius
borderBottomLeftRadius
类型 |
---|
Text |
textBreakStrategy
Android
在 Android API Level 23+ 上设置文本换行策略,可能的值为 simple
、highQuality
、balanced
。默认值为 highQuality
。
类型 |
---|
enum('simple', 'highQuality', 'balanced') |
underlineColorAndroid
Android
TextInput
下划线的颜色。
类型 |
---|
color |
value
要为文本输入显示的值。TextInput
是一个受控组件,这意味着如果提供此 value prop,则原生值将被强制与此值 prop 匹配。对于大多数用途,这非常有效,但在某些情况下,这可能会导致闪烁 - 一个常见原因是保持 value 不变以防止编辑。除了设置相同的值之外,还可以设置 editable={false}
,或设置/更新 maxLength
以防止不必要的编辑而不会闪烁。
类型 |
---|
string |
lineBreakStrategyIOS
iOS
在 iOS 14+ 上设置换行策略。可能的值为 none
、standard
、hangul-word
和 push-out
。
类型 | 默认 |
---|---|
枚举 ('none' , 'standard' , 'hangul-word' , 'push-out' ) | 'none' |
disableKeyboardShortcuts
iOS
如果 true
,则键盘快捷键(撤销/重做和复制按钮)将被禁用。默认值为 false
。
类型 |
---|
bool |
方法
.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
。