文本输入

通过键盘将文本输入到应用程序的一个基本的组件。属性提供几个功能的可配置性,比如自动校正,自动还原,占位符文本,和不同的键盘类型,如数字键盘。
最简单的一个用例是放置一个 TextInput,利用 onChangeText 事件来读取用户的输入。还有其他的事件可以使用,比如onSubmitEditingonFocus。一个简单的例子:

  1. <View>
  2. <TextInput
  3. style={{height: 40, borderColor: 'gray', borderWidth: 1}}
  4. onChangeText={(text) => this.setState({input: text})}
  5. />
  6. <Text>{'user input: ' + this.state.input}</Text>
  7. </View>

value 属性可以用于设置输入的值,其目的是让组件的状态更清晰,但是<TextInput> 所有的选项都是异步的,所以默认情况下它并不表现的像一个真正的控制组件。就像设置默认值一样设置 value 一次,但是你同样可以根据 onChangeText 不断的改变它的值。如果你真的想要迫使组件一直都可以恢复到你设置的值,那么你可以设置成 controlled={true}

不是所有版本都支持 multiline 属性,然后有些属性只支持多行输入。

属性

Edit on GitHub

autoCapitalize enum(‘none’, ‘sentences’, ‘words’, ‘characters’)

可以通知文本输入自动利用某些字符。

  • characters:所有字符,
  • words:每一个单词的首字母
  • sentences:每个句子的首字母(默认情况下)
  • none:不会自动使用任何东西

autoCorrect 布尔型

如果值为假,禁用自动校正。默认值为真。

autoFocus 布尔型

如果值为真,聚焦 componentDidMount 上的文本。默认值为假。

bufferDelay 数值型

这个会帮助避免由于 JS 和原生文本输入之间的竞态条件而丢失字符。默认值应该是没问题的,但是如果你每一个按键都操作的非常缓慢,那么你可能想尝试增加这个。

clearButtonMode enum(‘never’, ‘while-editing’, ‘unless-editing’, ‘always’)

清除按钮出现在文本视图右侧的时机

controlled 布尔型

如果你真想要它表现成一个控制组件,你可以将它的值设置为真,但是按下按键,并且/或者缓慢打字,你可能会看到它闪烁,这取决于你如何处理 onChange 事件。

editable 布尔型

如果值为假,文本是不可编辑的。默认值为真。

enablesReturnKeyAutomatically 布尔型

如果值为真,当没有文本的时候键盘是不能返回键值的,当有文本的时候会自动返回。默认值为假。

keyboardType enum(‘default’, “ascii-capable”, ‘numbers-and-punctuation’, ‘url’, ‘number-pad’, ‘phone-pad’, ‘name-phone-pad’, ‘email-address’, ‘decimal-pad’, ‘twitter’, ‘web-search’, “numeric”)

决定打开哪种键盘,例如,数字键盘。

multiline 布尔型

如果值为真,文本输入可以输入多行。默认值为假。

onBlur 函数

当文本输入是模糊的,调用回调函数

onChange 函数

当文本输入的文本发生变化时,调用回调函数

onChangeText 函数

onEndEditing 函数

onFocus 函数

当输入的文本是聚焦状态时,调用回调函数

onSubmitEditing 函数

password 布尔型

如果值为真,文本输入框就成为一个密码区域。默认值为假。

placeholder 字符串型

在文本输入之前字符串将被呈现出来

placeholderTextColor 字符串型

占位符字符串的文本颜色

returnKeyType enum(‘default’, ‘go’, ‘google’, ‘join’, ‘next’, ‘route’, ‘search’, ‘send’, ‘yahoo’, ‘done’, ‘emergency-call’)

决定返回键的样式

secureTextEntry 布尔型

如果值为真,文本输入框就会使输入的文本变得模糊,以便于像密码这样敏感的文本保持安全。默认值为假。

selectionState 文档选择状态

见 DocumentSelectionState.js,一些状态是为了维护一个文档的选择信息。

style Text#style

testID 字符串型

用于端对端测试时定位视图。

value 字符串型

文本输入的默认值

例子

Edit on GitHub

  1. 'use strict';
  2. var React = require('react-native');
  3. var {
  4. Text,
  5. TextInput,
  6. View,
  7. StyleSheet,
  8. } = React;
  9. var WithLabel = React.createClass({
  10. render: function() {
  11. return (
  12. <View style={styles.labelContainer}>
  13. <View style={styles.label}>
  14. <Text>{this.props.label}</Text>
  15. </View>
  16. {this.props.children}
  17. </View>
  18. );
  19. }
  20. });
  21. var TextEventsExample = React.createClass({
  22. getInitialState: function() {
  23. return {
  24. curText: '<No Event>',
  25. prevText: '<No Event>',
  26. };
  27. },
  28. updateText: function(text) {
  29. this.setState({
  30. curText: text,
  31. prevText: this.state.curText,
  32. });
  33. },
  34. render: function() {
  35. return (
  36. <View>
  37. <TextInput
  38. autoCapitalize="none"
  39. placeholder="Enter text to see events"
  40. autoCorrect={false}
  41. onFocus={() => this.updateText('onFocus')}
  42. onBlur={() => this.updateText('onBlur')}
  43. onChange={(event) => this.updateText(
  44. 'onChange text: ' + event.nativeEvent.text
  45. )}
  46. onEndEditing={(event) => this.updateText(
  47. 'onEndEditing text: ' + event.nativeEvent.text
  48. )}
  49. onSubmitEditing={(event) => this.updateText(
  50. 'onSubmitEditing text: ' + event.nativeEvent.text
  51. )}
  52. style={styles.default}
  53. />
  54. <Text style={styles.eventLabel}>
  55. {this.state.curText}{'\n'}
  56. (prev: {this.state.prevText})
  57. </Text>
  58. </View>
  59. );
  60. }
  61. });
  62. var styles = StyleSheet.create({
  63. page: {
  64. paddingBottom: 300,
  65. },
  66. default: {
  67. height: 26,
  68. borderWidth: 0.5,
  69. borderColor: '#0f0f0f',
  70. padding: 4,
  71. flex: 1,
  72. fontSize: 13,
  73. },
  74. multiline: {
  75. borderWidth: 0.5,
  76. borderColor: '#0f0f0f',
  77. flex: 1,
  78. fontSize: 13,
  79. height: 50,
  80. },
  81. eventLabel: {
  82. margin: 3,
  83. fontSize: 12,
  84. },
  85. labelContainer: {
  86. flexDirection: 'row',
  87. marginVertical: 2,
  88. flex: 1,
  89. },
  90. label: {
  91. width: 80,
  92. justifyContent: 'flex-end',
  93. flexDirection: 'row',
  94. marginRight: 10,
  95. paddingTop: 2,
  96. },
  97. });
  98. exports.title = '<TextInput>';
  99. exports.description = 'Single-line text inputs.';
  100. exports.examples = [
  101. {
  102. title: 'Auto-focus',
  103. render: function() {
  104. return <TextInput autoFocus={true} style={styles.default} />;
  105. }
  106. },
  107. {
  108. title: 'Auto-capitalize',
  109. render: function() {
  110. return (
  111. <View>
  112. <WithLabel label="none">
  113. <TextInput
  114. autoCapitalize="none"
  115. style={styles.default}
  116. />
  117. </WithLabel>
  118. <WithLabel label="sentences">
  119. <TextInput
  120. autoCapitalize="sentences"
  121. style={styles.default}
  122. />
  123. </WithLabel>
  124. <WithLabel label="words">
  125. <TextInput
  126. autoCapitalize="words"
  127. style={styles.default}
  128. />
  129. </WithLabel>
  130. <WithLabel label="characters">
  131. <TextInput
  132. autoCapitalize="characters"
  133. style={styles.default}
  134. />
  135. </WithLabel>
  136. </View>
  137. );
  138. }
  139. },
  140. {
  141. title: 'Auto-correct',
  142. render: function() {
  143. return (
  144. <View>
  145. <WithLabel label="true">
  146. <TextInput autoCorrect={true} style={styles.default} />
  147. </WithLabel>
  148. <WithLabel label="false">
  149. <TextInput autoCorrect={false} style={styles.default} />
  150. </WithLabel>
  151. </View>
  152. );
  153. }
  154. },
  155. {
  156. title: 'Keyboard types',
  157. render: function() {
  158. var keyboardTypes = [
  159. 'default',
  160. 'ascii-capable',
  161. 'numbers-and-punctuation',
  162. 'url',
  163. 'number-pad',
  164. 'phone-pad',
  165. 'name-phone-pad',
  166. 'email-address',
  167. 'decimal-pad',
  168. 'twitter',
  169. 'web-search',
  170. 'numeric',
  171. ];
  172. var examples = keyboardTypes.map((type) => {
  173. return (
  174. <WithLabel key={type} label={type}>
  175. <TextInput
  176. keyboardType={type}
  177. style={styles.default}
  178. />
  179. </WithLabel>
  180. );
  181. });
  182. return <View>{examples}</View>;
  183. }
  184. },
  185. {
  186. title: 'Return key types',
  187. render: function() {
  188. var returnKeyTypes = [
  189. 'default',
  190. 'go',
  191. 'google',
  192. 'join',
  193. 'next',
  194. 'route',
  195. 'search',
  196. 'send',
  197. 'yahoo',
  198. 'done',
  199. 'emergency-call',
  200. ];
  201. var examples = returnKeyTypes.map((type) => {
  202. return (
  203. <WithLabel key={type} label={type}>
  204. <TextInput
  205. returnKeyType={type}
  206. style={styles.default}
  207. />
  208. </WithLabel>
  209. );
  210. });
  211. return <View>{examples}</View>;
  212. }
  213. },
  214. {
  215. title: 'Enable return key automatically',
  216. render: function() {
  217. return (
  218. <View>
  219. <WithLabel label="true">
  220. <TextInput enablesReturnKeyAutomatically={true} style={styles.default} />
  221. </WithLabel>
  222. </View>
  223. );
  224. }
  225. },
  226. {
  227. title: 'Secure text entry',
  228. render: function() {
  229. return (
  230. <View>
  231. <WithLabel label="true">
  232. <TextInput secureTextEntry={true} style={styles.default} value="abc" />
  233. </WithLabel>
  234. </View>
  235. );
  236. }
  237. },
  238. {
  239. title: 'Event handling',
  240. render: function(): ReactElement { return <TextEventsExample /> },
  241. },
  242. {
  243. title: 'Colored input text',
  244. render: function() {
  245. return (
  246. <View>
  247. <TextInput
  248. style={[styles.default, {color: 'blue'}]}
  249. value="Blue"
  250. />
  251. <TextInput
  252. style={[styles.default, {color: 'green'}]}
  253. value="Green"
  254. />
  255. </View>
  256. );
  257. }
  258. },
  259. {
  260. title: 'Clear button mode',
  261. render: function () {
  262. return (
  263. <View>
  264. <WithLabel label="never">
  265. <TextInput
  266. style={styles.default}
  267. clearButtonMode="never"
  268. />
  269. </WithLabel>
  270. <WithLabel label="while editing">
  271. <TextInput
  272. style={styles.default}
  273. clearButtonMode="while-editing"
  274. />
  275. </WithLabel>
  276. <WithLabel label="unless editing">
  277. <TextInput
  278. style={styles.default}
  279. clearButtonMode="unless-editing"
  280. />
  281. </WithLabel>
  282. <WithLabel label="always">
  283. <TextInput
  284. style={styles.default}
  285. clearButtonMode="always"
  286. />
  287. </WithLabel>
  288. </View>
  289. );
  290. }
  291. },
  292. ];