React Native - 文本输入框(TextInput)的使用详解
一、基本介绍
1,TextInput组件介绍
TextInput 组件除了作为输入框实现基本的输入功能外,它还提供了许多其他功能,比如自动校验、占位符以及指定弹出不同的键盘类型等。
2,组件的通用属性
(1)autoCapitalize:首字母自动大写。可选值有:none、sentences、words、characters。
- none:不自动变为大写
- sentences:将每句话的首字母自动改成大写
- words:将每个单词的首字母自动改成大写
- characters:将每个英文字母自动改为大写
(2)placeholder:占位符,在输入前显示的文本内容。
(3)value:用来设置 TextInput 组件内字符串的值。
- 要慎重使用这个属性,因为它有可能会带来屏幕显示闪烁。
- 官方更推荐使用 editable 属性和 defaultValue 属性来达到相同的效果。
- 当然如果应用需要突然改变 TextInput 组件内字符串的值,还是需要使用这个属性。
(4)placeholderTextColor:占位符文本的颜色。
(5)password:如果为 true,表示密码输入框。文本显示为“*”
(6)multiline:如果为 true,表示多行输入。
(7)editable:默认为 true。如果设置为 false 表示不可编辑。
(8)autoFocus:如果为 true,则自动获取焦点。
(9)maxLength:能够输入的最长字符数。
(10)returnKeyType:表示软键盘返回键显示的字符串。可选值如下:
- 跨平台支持的值:done、go、next、search、send
- 仅 Android 支持的值:none、previous
- 仅 iOS 支持的值:default、google、join、route、yahoo、emergency-call
(11)keyboardType:定义了当 TextInput 组件获得焦点时,将自动弹出哪种软键盘。可选值如下:
- Android、iOS 都支持的:default、numeric、email-address
- 仅支持 iOS:ascii-capable、numbers-and-punctuation、url、number-pad、phone-pad、name-phone-pad、decimal-pad、twitter、web-search
(12)secureTextEntry:默认为 false。如果为 true,则像密码框一样隐藏输入内容。
(13)autoCorrect:如果为 true,则会自动更正用户输入的英文单词是否正确。(默认值:true)
(14)blurOnSubmit:如果为 true,在输入框输入完成提交是,文本区域会被模糊化。它的默认值是 TextInput 组件 multiline 属性的非值。如果一个 TextInput 组件的 multiline 属性与 blurOnSubmit 都为 true 时,用户按下键盘上的回车键会模糊化输入的文本并触发 onSubmitEditing 事件,而不是在输入区域插入新行。
(15)defaultValue:用来定义 TextInput 组件中的字符串默认值。
(16)selectTextOnFocus:当它为 true 时,如果 TextInput 组件获得焦点,则组件中所有的文字都会被选中。
(17)selection:这个是一个对象类型的属性。它接受的对象结构为:
{ start: number, end: number }
- 我们可以用来设置 TextInput 组件中被选择字符的开始与结束位置。
- 如果把开始位置与结束位置设为同一个值可以达到设置输入光标至该位置的效果。
(18)selectionColor:用来设置被选中文字的高亮显示颜色。在 iOS 平台,还可以使用这个属性设置输入光标的颜色。
3,组件 iOS 平台专有属性
(1)clearButtonMode:表示什么时候会显示清除按钮。可选值有:never、while-editing、unless-editing、always。
(2)clearTextOnFocus:如果为 true,当用户点击 TextInput 组件开始编辑文字时,会自动清除文字区域。
(3)enablesReturnKeyAutomatically:默认为 false。设置为 true 表示没有输入文本时返回键无法使用。
(4)keyboardAppearance:设置不同的键盘颜色。可选值有:default、light、dark,分别表示默认、明亮、偏暗。
4, 组件 Android 平台专有属性
(1)numberOfLines:用来设置 TextInput 组件可以有多少行。
(2)disableFullscreenUI:是否开启全屏文本输入模式。默认为 false。
- 当为 false 时,如果手机操作系统发现 TextInput 组件的空间小,可能会让用户进入一个全屏文本输入的模式。
- 当为 true 时,操作系统的这个特性会被关闭,用户只能在 TextInput 组件中进行输入。
(3)inlineImageLeft:它必须是 RN 的 Android 工程中的一个图片资源的名称。RN 将会把这张图片无缩放地显示在 TextInput 组件的左侧。
(4)inlineImagePadding:它定义了 inlineImage(如果有的话)的 padding 与 TextInput 组件自己的 padding。
(5)returnKeyLabel:使用这个属性可以将手机软键盘的回车键设为指定的字符串。这个属性的优先级高于 returnKeyType。
(6)underlineColorAndroid:用来定义输入提示下划线的颜色。如果将它的颜色设为与 TextInput 组件的背景色一样,即可以隐藏输入提示下划线。
5,组件的方法属性
(1)onChange:当文本发生变化时,调用该函数。
- 它的回调接收一个 event 参数,通过 event.nativeEvent.text 可以获取用户输入的字符串。
(2)onChangeText:当文本发生变化时,调用该函数。
- onChangeText 回调函数与上面的 onChange 类似,但它的好处是直接可以接收用户输入的字符串。
(3)onEndEditing:当结束编辑时,调用该函数。
- 它的回调接收一个 event 参数,通过 event.nativeEvent.text 可以获取用户输入的字符串。
(4)onBlur:失去焦点时触发(在 onEndEditing 之后)。
- 它的回调接收一个 event 参数,通过 event.nativeEvent.text 可以获取用户输入的字符串。
(5)onFocus:获得焦点时触发。
- 它的回调接收一个 event 参数,通过 event.nativeEvent.text 可以获取组件中的字符串(上次输入的,或者是程序设定的默认值)
(6)onSubmitEditing:当结束编辑后,点击键盘的提交按钮触发该事件。
- 它的回调接收一个 event 参数,通过 event.nativeEvent.text 可以获取用户输入的字符串。
当我们通过 multiline={true} 将一个 TextInput 组件设置为多行时,要注意:
- 在 iOS 平台上,这个 TextInput 组件的 onSubmitEditing 事件永远也不会被触发,onSubmitEditing 回调函数也永远不会被执行。
- 在 Android 平台上,用户每一次按下回车键后,onSubmitEditing 事件都会被触发,但输入框中的字符串会增加一个回车换行,同时输入框会继续保持住焦点,不会失去焦点。
(7)onSelectionChange:当用户在文本输入框中选择的字符串发生改变时触发。
- 该回调函数会传入一个 event 参数,通过这个参数我们可以得到用户在输入框中选择一段字符串这个事件发生的时间,以及选择的子字符串在输入框中的起点位置与结束位置。
{ timeStamp: 事件发生时的时间值 nativeEvent: { selection: { start: 用户选中的子字符串起点位置 end: 用户选中的子字符串结束位置 } } }
- 当用户移动输入光标时,这个事件也会被触发。比如我们将 TextInput 组件的输入光标移动到最开始位置,那么 event.nativeEvent.selection.start 和 event.nativeEvent.selection.end 的值都是 0。
{ nativeEvent: { contentSize: { width: number, height: number } } }
(10)onScroll:在 TextInput 组件滚动时会被调用。它的参数是一个对象,我们可以从中得到组件当前滚动的位置。
{ nativeEvent: { contentOffset: { x: number, y: number } } }
(11)onSelectionChange:会在 TextInput 组件的选中字符被改变时调用。它的参数是一个对象,我们可以通过其得到用户选择的字符串。
{ nativeEvent: { selection: { start: number, end: number } } }
6,组件的成员函数
(1)isFocused()
当得到一个 TextInput 组件的引用后,通过这个方法可以判断当前这个 TextInput 组件是否获得焦点。
this.refs.aTextInputRef.isFocused();
(2)clear()
当得到一个 TextInput 组件的引用后,通过这个方法可以将 TextInput 组件中的字符串清空。
this.refs.aTextInputRef.clear();
二、不同平台上的不同表现
1,高度适配
- 在 Android 平台上 TextInput 组件可以按照其字体大小自动设置高度,所以 TextInput 组件在 Android 平台上可以不设置组件高度。
- 而在 iOS 平台上必须要设置组件高度,否则 TextInput 组件将不会显示。
2,输入框下划线
(1)在 Andorid 平台上输入框区域有一条下划线,提示用户这里是一个输入框。

注意:这条下划线默认颜色值时 gray。如果想让这条下划线消失,可以让下划线的颜色与 TextInput 组件的背景色相同,或者让 TextInput 组件的背景色比下划线颜色深。
(2)在 iOS 平台上输入框区域是没有这条下划线的。
3,父组件的 alignItems 键失效
如果我们想让某个组件内的所有子组件都居中对齐,通常可以将该组件 alignItems 样式设置成 center。当如果子组件是 TextInput,那么在不同的平台下表现是不同的。
(1)在 Android 平台下,如果父组件设置了 alignItems:'center',那么 TextInput 组件是会正确居中对齐的。

(2)但在 iOS 平台下,即使父组件设置了 alignItems:'center',TextInput 组件仍然是居左对齐。为了让 iOS 平台的 TextInput 组件遵从父组件的对齐规则,需要将 TextInput 组件使用一个没有任何属性的 View 组件包围起来。
<View style={[styles.flex, styles.container]}> <View> <TextInput style={styles.textInputStyle} defaultValue="欢迎访问 hangge.com"> </TextInput> </View> </View>
三、使用样例
(1)效果图
- 页面上添加一个 TextInput 用于输入文字,并设置相关的占位符文字以及样式。
- 当输入框文字改变时,下方 Text 组件会实时统计并显示输入的文字长度。
- 点击输入框右侧“搜索”按钮,则将输入框内容弹出显示。



import React, { Component } from 'react'; import { AppRegistry, StyleSheet, Text, View, TextInput, } from 'react-native'; //输入框组件 class Search extends Component { //构造函数 constructor(props) { super(props); this.state = {text: ''}; } //组件渲染 render() { return ( <View style={styles.flex}> <View style={[styles.flexDirection, styles.inputHeight]}> <View style={styles.flex}> <TextInput style={styles.input} returnKeyType="search" placeholder="请输入关键字" onChangeText={(text) => this.setState({text})}/> </View> <View style={styles.btn}> <Text style={styles.search} onPress={this.search.bind(this)}>搜索</Text> </View> </View> <Text style={styles.tip}>已输入{this.state.text.length}个文字</Text> </View> ); } //搜索按钮点击 search(){ alert("您输入的内容为:"+this.state.text); } } //默认应用的容器组件 class App extends Component { render() { return ( <View style={[styles.flex, styles.topStatus]}> <Search></Search> </View> ); } } //样式定义 const styles = StyleSheet.create({ flex:{ flex: 1, }, flexDirection:{ flexDirection:'row' }, topStatus:{ marginTop:25, }, inputHeight:{ height:45, }, input:{ height:45, borderWidth:1, marginLeft: 5, paddingLeft:5, borderColor: '#ccc', borderRadius: 4 }, btn:{ width:55, marginLeft:-5, marginRight:5, backgroundColor:'#23BEFF', height:45, justifyContent:'center', alignItems: 'center' }, search:{ color:'#fff', fontSize:15, fontWeight:'bold' }, tip:{ marginLeft: 5, marginTop: 5, color: '#C0C0C0', } }); AppRegistry.registerComponent('HelloWorld', () => App);