TextInput
参考文档
TextInput是一个允许用户在应用中通过键盘输入文本的基本组件。本组件的属性提供了多种特性的配置,譬如自动完成、自动大小写、占位文字,以及多种不同的键盘类型(如纯数字键盘)等等。
TextInput在安卓上默认有一个底边框,同时会有一些padding。如果要想使其看起来和iOS上尽量一致,则需要设置padding: 0,同时设置underlineColorAndroid="transparent"来去掉底边框。
又,在安卓上如果设置multiline = {true},文本默认会垂直居中,可设置textAlignVertical: 'top'样式来使其居顶显示。
又又,在安卓上长按选择文本会导致windowSoftInputMode设置变为adjustResize,这样可能导致绝对定位的元素被键盘给顶起来。要解决这一问题你需要在AndroidManifest.xml中明确指定合适的windowSoftInputMode( https://developer.android.com/guide/topics/manifest/activity-element.html )值,或是自己监听事件来处理布局变化。
属性Props
属性 | 类型 | 必填 | 描述 |
allowFontScaling | bool | 否 | 控制字体是否要根据系统的“字体大小”辅助选项来进行缩放。默认值为true。 |
autoCapitalize | enum('none', 'sentences', 'words', 'characters') | 否 |
控制TextInput是否要自动将特定字符切换为大写:
characters: 所有的字符。 words: 每个单词的第一个字符。 sentences: 每句话的第一个字符(默认)。 none: 不切换。 |
autoCorrect | bool | 否 | 如果为false,会关闭拼写自动修正。默认值是true。 |
autoFocus | bool | 否 | 如果为true,在componentDidMount后会获得焦点。默认值为false。 |
blurOnSubmit | bool | 否 | 如果为true,文本框会在提交的时候失焦。对于单行输入框默认值为true,多行则为false。注意:对于多行输入框来说,如果将blurOnSubmit设为true,则在按下回车键时就会失去焦点同时触发onSubmitEditing事件,而不会换行。 |
caretHidden | bool | 否 | 如果为true,则隐藏光标。默认值为false。 |
clearButtonMode | enum('never', 'while-editing', 'unless-editing', 'always') | 否 | 是否要在文本框右侧显示“清除”按钮。仅在单行模式下可用。 (ios平台) |
clearTextOnFocus | bool | 否 | 如果为true,每次开始输入的时候都会清除文本框的内容。 (ios平台) |
contextMenuHidden | bool | 否 | 如果为true,则上下文菜单被隐藏。 默认值为false。 |
dataDetectorTypes | enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') | 否 | 设置 text input 内能被转化为可点击URL的数据的类型。当且仅当multiline={true}和editable={false}时起作用。默认情况下不检测任何数据类型。 可接受一个类型值或类型值数组。 dataDetectorTypes的可用值有: 'phoneNumber' 'link' 'address' 'calendarEvent' 'none' 'all' (ios平台) |
defaultValue | string | 否 | 提供一个文本框中的初始值。当用户开始输入的时候,值就可以改变。在一些简单的使用情形下,如果你不想用监听消息然后更新value属性的方法来保持属性和状态同步的时候,就可以用defaultValue来代替。 |
disableFullscreenUI | bool | 否 | 当值为false时, 如果 text input 的周围有少量可用空间的话(比如说,当手机横过来时),操作系统可能会将这个 text input 设置为全屏模式。当值为true时, 这个特性不可用,text input 就是普通的模式。默认为false。 (Android 平台) |
editable | bool | 否 | 如果为false,文本框是不可编辑的。默认值为true。 |
enablesReturnKeyAutomatically | bool | 否 | 如果为true,键盘会在文本框内没有文字的时候禁用确认按钮。默认值为false。 (ios 平台) |
inlineImageLeft | string | 否 |
指定一个图片放置在左侧。图片必须放置在/android/app/src/main/res/drawable目录下,经过编译后按如下形式引用(无路径无后缀):
(Android 平台)
|
inlineImagePadding | number | 否 | 给放置在左侧的图片设置padding样式 (Android 平台) |
keyboardAppearance | enum('default', 'light', 'dark') | 否 | 指定键盘的颜色 (iOS 平台) |
keyboardType | 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') | 否 |
决定弹出的何种软键盘的,譬如numeric(纯数字键盘)。
这些值在所有平台都可用:
default numeric email-address phone-pad 下面的值仅iOS可用: ascii-capable numbers-and-punctuation url number-pad name-phone-pad decimal-pad web-search 下面的值仅Android可用: visible-password |
maxLength | number | 否 | 限制文本框中最多的字符数。使用这个属性而不用JS逻辑去实现,可以避免闪烁的现象。 |
multiline | bool | 否 | 如果为true,文本框中可以输入多行文字。默认值为false。注意安卓上如果设置multiline = {true},文本默认会垂直居中,可设置textAlignVertical: 'top'样式来使其居顶显示。 |
numberOfLines | number | 否 | 设置输入框的行数。当multiline设置为true时使用它,可以占据对应的行数。 (Android 平台) |
onBlur | function | 否 | 当文本框失去焦点的时候调用此回调函数。 |
onChange | function | 否 | 当文本框内容变化时调用此回调函数。 |
onChangeText | function | 否 | 当文本框内容变化时调用此回调函数。改变后的文字内容会作为参数传递。 |
onContentSizeChange | function | 否 | 文本输入的内容大小更改时调用的回调。 这将通过{nativeEvent:{contentSize:{width,height}}}进行调用。 仅用于多行文本输入。 |
onEndEditing | function | 否 | 当文本输入结束后调用此回调函数。 |
onFocus | function | 否 | 当文本框获得焦点的时候调用此回调函数。 |
onKeyPress | function | 否 | 当一个键被按下的时候调用此回调。传递给回调函数的参数为{ nativeEvent: { key: keyValue } },其中keyValue即为被按下的键。会在onChange之前调用。注意:在Android上只有软键盘会触发此事件,物理键盘不会触发。 |
onLayout | function | 否 | 当组件加载或者布局变化的时候调用,参数为{x, y, width, height}。 |
onScroll | function | 否 | 在内容滚动时持续调用,传回参数的格式形如{ nativeEvent: { contentOffset: { x, y } } }。也可能包含其他和滚动事件相关的参数,但是在Android上,出于性能考虑,不会提供contentSize参数。 |
onSelectionChange | function | 否 | 长按选择文本时,选择范围变化时调用此函数,传回参数的格式形如{ nativeEvent: { selection: { start, end } } }。 |
onSubmitEditing | function | 否 | 此回调函数当软键盘的确定/提交按钮被按下的时候调用此函数。如果multiline={true},此属性不可用 |
placeholder | string | 否 | 如果没有任何文字输入,会显示此字符串。 |
placeholderTextColor | color | 否 | 占位字符串显示的文字颜色。 |
returnKeyLabel | string | 否 | 将返回键设置为标签。 使用它代替returnKeyType。 (Android 平台) |
returnKeyType | enum('done', 'go', 'next', 'search', 'send', 'none', 'previous', 'default', 'emergency-call', 'google', 'join', 'route', 'yahoo') | 否 |
决定“确定”按钮显示的内容。在Android上你还可以使用returnKeyLabel。
下列这些选项是跨平台可用的:
done go next search send 下列这些选项仅Android可用: none previous 下列这些选项仅iOS可用: default emergency-call join route yahoo |
secureTextEntry | bool | 否 | 如果为true,文本框会遮住之前输入的文字,这样类似密码之类的敏感文字可以更加安全。默认值为false。multiline={true}时不可用。 |
selection | object: {start: number,end: number} | 否 | 设置选中文字的范围(指定首尾的索引值)。如果首尾为同一索引位置,则相当于指定光标的位置。 |
selectionColor | color | 否 | 设置输入框高亮时的颜色(还包括光标)。 |
selectionState | DocumentSelectionState | 否 |
DocumentSelectionState的实例,可以控制一个文档中哪段文字被选中的状态。
此实例可以执行的一些功能是:
blur() focus() update() (iOS 平台) |
selectTextOnFocus | bool | 否 | 如果为true,当获得焦点的时候,所有的文字都会被选中 |
spellCheck | bool | 否 | 如果设置为false,则禁用拼写检查的样式(比如错误拼写的单词下的红线)。默认值继承自autoCorrect。 (ios 平台) |
textContentType | enum('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') | 否 |
为键盘和系统提供有关用户输入内容的预期语义的信息。
对于iOS 11+,您可以将textContentType设置为用户名或密码,以启用设备钥匙串中的登录详细信息自动填充。
要禁用自动填充,请将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 |
style | Text | 否 |
请注意,并非所有文本样式都受支持,不支持的样式的不完整列表包括:
borderLeftWidth borderTopWidth borderRightWidth borderBottomWidth borderTopLeftRadius borderTopRightRadius borderBottomRightRadius borderBottomLeftRadius |
textBreakStrategy | enum('simple', 'highQuality', 'balanced') | 否 | 在 Android API Level 23+ 的平台上设置文字断行策略, 可能值有simple, highQuality, balanced。默认值为simple。 (Android 平台) |
underlineColorAndroid | color | 否 | 文本框的下划线颜色(译注:如果要去掉文本框的边框,请将此属性设为透明transparent)。 (Android 平台) |
value | string | 否 | 文本框中的文字内容。 TextInput是一个受约束的(Controlled)的组件,意味着如果提供了value属性,原生值会被强制与value属性保持一致。在大部分情况下这都工作的很好,不过有些情况下会导致一些闪烁现象——一个常见的原因就是通过不改变value来阻止用户进行编辑。如果你希望阻止用户输入,可以考虑设置editable={false};如果你是希望限制输入的长度,可以考虑设置maxLength属性,这两个属性都不会导致闪烁。 |
方法
clear()
清空输入框的内容。
isFocused()
返回值表明当前输入框是否获得了焦点。
Example
示例1
简单的用法就是丢一个TextInput到应用里,然后订阅它的onChangeText事件来读取用户的输入。注意,从TextInput里取值这就是目前唯一的做法!也就是使用在onChangeText中用setState把用户的输入写入到state中,然后在需要取值的地方从this.state中取出值。它还有一些其它的事件,譬如onSubmitEditing和onFocus。一个简单的例子如下
import React, { Component } from 'react';
import { TextInput,StyleSheet } from 'react-native';
export class pageComponent extends Component {
constructor(props) {
super(props);
this.state = { text: 'Useless Placeholder' };
}
render() {
return (
<TextInput
style={styles.textInput}
onChangeText={(text) => this.setState({text})}
value={this.state.text}
/>
);
}
}
const styles = StyleSheet.create({
textInput: {
height: 40,
borderColor: 'gray',
borderWidth: 1
},
});
它的两个方法.focus()和.blur(),它们分别是使TextInput获取和失去焦点。
示例2
注意有些属性仅在multiline为true或者为false的时候有效。此外,当multiline=false时,为元素的某一个边添加边框样式(例如:borderBottomColor,borderLeftWidth等)将不会生效。为了能够实现效果你可以使用一个View来包裹TextInput:
import React, { Component } from 'react';
import {View,TextInput,StyleSheet } from 'react-native';
class UselessTextInput extends Component {
render() {
return (
<TextInput
{...this.props} // 将父组件传递来的所有props传递给TextInput;比如下面的multiline和numberOfLines
editable = {true}
maxLength = {40}
/>
);
}
}
export class pageComponent extends Component {
constructor(props) {
super(props);
this.state = {
text: 'Useless Multiline Placeholder',
};
}
// 你可以试着输入一种颜色,比如red,那么这个red就会作用到View的背景色样式上
render() {
let viewStyle={
backgroundColor: this.state.text,
borderBottomColor: '#000000',
borderBottomWidth: 1,
marginTop:100
}
return (
<View style={viewStyle}>
<UselessTextInput
multiline = {true}
numberOfLines = {4}
onChangeText={(text) => this.setState({text})}
value={this.state.text}
/>
</View>
);
}
}