status-im/react-native
2
0
Fork 0
mirror of https://github.com/status-im/react-native.git synced 2025-02-27 08:30:34 +00:00
Code Issues Projects Releases Wiki Activity

Update TextInput API

Browse Source 
Summary:
- Make the examples runnable (both copy/paste and with the web player)
- Add a bit more information in props where needed.
Closes https://github.com/facebook/react-native/pull/8392

Differential Revision: D3482747

Pulled By: caabernathy

fbshipit-source-id: 8f2d812efc1efb3f14db45b5c054ce0d5c14f5f5
This commit is contained in:
Joel Marcey 2016-06-24 11:53:30 -07:00 committed by Facebook Github Bot 8
parent 64cdc3547c
commit 91134d16c9
1 changed files with 145 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
Libraries/Components/TextInput/TextInput.js
View File

@ -57,12 +57,29 @@ type Event = Object;
* such as `onSubmitEditing` and `onFocus` that can be subscribed to. A simple * such as `onSubmitEditing` and `onFocus` that can be subscribed to. A simple
* example: * example:
* *
* ``` * ```ReactNativeWebPlayer
* <TextInput * import React, { Component } from 'react';
* style={{height: 40, borderColor: 'gray', borderWidth: 1}} * import { AppRegistry, TextInput } from 'react-native';
* onChangeText={(text) => this.setState({text})} *
* value={this.state.text} * class UselessTextInput extends Component {
* /> * constructor(props) {
* super(props);
* this.state = { text: 'Useless Placeholder' };
* }
*
* render() {
* return (
* <TextInput
* style={{height: 40, borderColor: 'gray', borderWidth: 1}}
* onChangeText={(text) => this.setState({text})}
* value={this.state.text}
* />
* );
* }
* }
*
* // App registration and rendering
* AppRegistry.registerComponent('AwesomeProject', () => UselessTextInput);
* ``` * ```
* *
* Note that some props are only available with `multiline={true/false}`. * Note that some props are only available with `multiline={true/false}`.
@ -71,10 +88,55 @@ type Event = Object;
* `multiline=false`. To achieve the same effect, you can wrap your `TextInput` * `multiline=false`. To achieve the same effect, you can wrap your `TextInput`
* in a `View`: * in a `View`:
* *
* ``` * ```ReactNativeWebPlayer
* <View style={{ borderBottomColor: '#000000', borderBottomWidth: 1, }}> * import React, { Component } from 'react';
* <TextInput {...props} /> * import { AppRegistry, View, TextInput } from 'react-native';
* </View> *
* class UselessTextInput extends Component {
* render() {
* return (
* <TextInput
* {...this.props} // Inherit any props passed to it; e.g., multiline, numberOfLines below
* editable = {true}
* maxLength = {40}
* />
* );
* }
* }
*
* class UselessTextInputMultiline extends Component {
* constructor(props) {
* super(props);
* this.state = {
* text: 'Useless Multiline Placeholder',
* };
* }
*
* // If you type something in the text box that is a color, the background will change to that
* // color.
* render() {
* return (
* <View style={{
* backgroundColor: this.state.text,
* borderBottomColor: '#000000',
* borderBottomWidth: 1 }}
* >
* <UselessTextInput
* multiline = {true}
* numberOfLines = {4}
* onChangeText={(text) => this.setState({text})}
* value={this.state.text}
* />
* </View>
* );
* }
* }
*
* // App registration and rendering
* AppRegistry.registerComponent(
* 'AwesomeProject',
* () => UselessTextInputMultiline
* );
* ``` * ```
* *
* `TextInput` has by default a border at the bottom of its view. This border * `TextInput` has by default a border at the bottom of its view. This border
@ -94,12 +156,12 @@ const TextInput = React.createClass({
propTypes: { propTypes: {
...View.propTypes, ...View.propTypes,
/** /**
* Can tell TextInput to automatically capitalize certain characters. * Can tell `TextInput` to automatically capitalize certain characters.
* *
* - characters: all characters, * - `characters`: all characters.
* - words: first letter of each word * - `words`: first letter of each word.
* - sentences: first letter of each sentence (default) * - `sentences`: first letter of each sentence (*default*).
* - none: don't auto capitalize anything * - `none`: don't auto capitalize anything.
*/ */
autoCapitalize: PropTypes.oneOf([ autoCapitalize: PropTypes.oneOf([
'none', 'none',
@ -108,16 +170,16 @@ const TextInput = React.createClass({
'characters', 'characters',
]), ]),
/** /**
* If false, disables auto-correct. The default value is true. * If `false`, disables auto-correct. The default value is `true`.
*/ */
autoCorrect: PropTypes.bool, autoCorrect: PropTypes.bool,
/** /**
* If true, focuses the input on componentDidMount. * If `true`, focuses the input on `componentDidMount`.
* The default value is false. * The default value is `false`.
*/ */
autoFocus: PropTypes.bool, autoFocus: PropTypes.bool,
/** /**
* If false, text is not editable. The default value is true. * If `false`, text is not editable. The default value is `true`.
*/ */
editable: PropTypes.bool, editable: PropTypes.bool,
/** /**
@ -125,9 +187,9 @@ const TextInput = React.createClass({
* *
* The following values work across platforms: * The following values work across platforms:
* *
* - default * - `default`
* - numeric * - `numeric`
* - email-address * - `email-address`
*/ */
keyboardType: PropTypes.oneOf([ keyboardType: PropTypes.oneOf([
// Cross-platform // Cross-platform
@ -158,27 +220,33 @@ const TextInput = React.createClass({
* Determines how the return key should look. On Android you can also use * Determines how the return key should look. On Android you can also use
* `returnKeyLabel`. * `returnKeyLabel`.
* *
* *Cross platform*
*
* The following values work across platforms: * The following values work across platforms:
* *
* - done * - `done`
* - go * - `go`
* - next * - `next`
* - search * - `search`
* - send * - `send`
*
* *Android Only*
* *
* The following values work on Android only: * The following values work on Android only:
* *
* - none * - `none`
* - previous * - `previous`
*
* *iOS Only*
* *
* The following values work on iOS only: * The following values work on iOS only:
* *
* - default * - `default`
* - emergency-call * - `emergency-call`
* - google * - `google`
* - join * - `join`
* - route * - `route`
* - yahoo * - `yahoo`
*/ */
returnKeyType: PropTypes.oneOf([ returnKeyType: PropTypes.oneOf([
// Cross-platform // Cross-platform
@ -209,28 +277,28 @@ const TextInput = React.createClass({
*/ */
maxLength: PropTypes.number, maxLength: PropTypes.number,
/** /**
* Sets the number of lines for a TextInput. Use it with multiline set to * Sets the number of lines for a `TextInput`. Use it with multiline set to
* true to be able to fill the lines. * `true` to be able to fill the lines.
* @platform android * @platform android
*/ */
numberOfLines: PropTypes.number, numberOfLines: PropTypes.number,
/** /**
* If true, the keyboard disables the return key when there is no text and * If `true`, the keyboard disables the return key when there is no text and
* automatically enables it when there is text. The default value is false. * automatically enables it when there is text. The default value is `false`.
* @platform ios * @platform ios
*/ */
enablesReturnKeyAutomatically: PropTypes.bool, enablesReturnKeyAutomatically: PropTypes.bool,
/** /**
* If true, the text input can be multiple lines. * If `true`, the text input can be multiple lines.
* The default value is false. * The default value is `false`.
*/ */
multiline: PropTypes.bool, multiline: PropTypes.bool,
/** /**
* Callback that is called when the text input is blurred * Callback that is called when the text input is blurred.
*/ */
onBlur: PropTypes.func, onBlur: PropTypes.func,
/** /**
* Callback that is called when the text input is focused * Callback that is called when the text input is focused.
*/ */
onFocus: PropTypes.func, onFocus: PropTypes.func,
/** /**
@ -247,18 +315,18 @@ const TextInput = React.createClass({
*/ */
onEndEditing: PropTypes.func, onEndEditing: PropTypes.func,
/** /**
* Callback that is called when the text input selection is changed * Callback that is called when the text input selection is changed.
*/ */
onSelectionChange: PropTypes.func, onSelectionChange: PropTypes.func,
/** /**
* Callback that is called when the text input's submit button is pressed. * Callback that is called when the text input's submit button is pressed.
* Invalid if multiline={true} is specified. * Invalid if `multiline={true}` is specified.
*/ */
onSubmitEditing: PropTypes.func, onSubmitEditing: PropTypes.func,
/** /**
* Callback that is called when a key is pressed. * Callback that is called when a key is pressed.
* Pressed key value is passed as an argument to the callback handler. * Pressed key value is passed as an argument to the callback handler.
* Fires before onChange callbacks. * Fires before `onChange` callbacks.
* @platform ios * @platform ios
*/ */
onKeyPress: PropTypes.func, onKeyPress: PropTypes.func,
@ -267,32 +335,42 @@ const TextInput = React.createClass({
*/ */
onLayout: PropTypes.func, onLayout: PropTypes.func,
/** /**
* The string that will be rendered before text input has been entered * The string that will be rendered before text input has been entered.
*/ */
placeholder: PropTypes.string, placeholder: PropTypes.string,
/** /**
* The text color of the placeholder string * The text color of the placeholder string.
*/ */
placeholderTextColor: ColorPropType, placeholderTextColor: ColorPropType,
/** /**
* If true, the text input obscures the text entered so that sensitive text * If `true`, the text input obscures the text entered so that sensitive text
* like passwords stay secure. The default value is false. * like passwords stay secure. The default value is `false`.
*/ */
secureTextEntry: PropTypes.bool, secureTextEntry: PropTypes.bool,
/** /**
* The highlight (and cursor on ios) color of the text input * The highlight (and cursor on iOS) color of the text input.
*/ */
selectionColor: ColorPropType, selectionColor: ColorPropType,
/** /**
* See DocumentSelectionState.js, some state that is responsible for * An instance of `DocumentSelectionState`, this is some state that is responsible for
* maintaining selection information for a document * maintaining selection information for a document.
*
* Some functionality that can be performed with this instance is:
*
* - `blur()`
* - `focus()`
* - `update()`
*
* > You can refernce `DocumentSelectionState` in
* > [`vendor/document/selection/DocumentSelectionState.js`](https://github.com/facebook/react-native/blob/master/Libraries/vendor/document/selection/DocumentSelectionState.js)
*
* @platform ios * @platform ios
*/ */
selectionState: PropTypes.instanceOf(DocumentSelectionState), selectionState: PropTypes.instanceOf(DocumentSelectionState),
/** /**
* The value to show for the text input. TextInput is a controlled * The value to show for the text input. `TextInput` is a controlled
* component, which means the native value will be forced to match this * component, which means the native value will be forced to match this
* value prop if provided. For most uses this works great, but in some * value prop if provided. For most uses, this works great, but in some
* cases this may cause flickering - one common cause is preventing edits * cases this may cause flickering - one common cause is preventing edits
* by keeping value the same. In addition to simply setting the same value, * by keeping value the same. In addition to simply setting the same value,
* either set `editable={false}`, or set/update `maxLength` to prevent * either set `editable={false}`, or set/update `maxLength` to prevent
@ -301,12 +379,12 @@ const TextInput = React.createClass({
value: PropTypes.string, value: PropTypes.string,
/** /**
* Provides an initial value that will change when the user starts typing. * Provides an initial value that will change when the user starts typing.
* Useful for simple use-cases where you don't want to deal with listening * Useful for simple use-cases where you do not want to deal with listening
* to events and updating the value prop to keep the controlled state in sync. * to events and updating the value prop to keep the controlled state in sync.
*/ */
defaultValue: PropTypes.string, defaultValue: PropTypes.string,
/** /**
* When the clear button should appear on the right side of the text view * When the clear button should appear on the right side of the text view.
* @platform ios * @platform ios
*/ */
clearButtonMode: PropTypes.oneOf([ clearButtonMode: PropTypes.oneOf([
@ -316,28 +394,28 @@ const TextInput = React.createClass({
'always', 'always',
]), ]),
/** /**
* If true, clears the text field automatically when editing begins * If `true`, clears the text field automatically when editing begins.
* @platform ios * @platform ios
*/ */
clearTextOnFocus: PropTypes.bool, clearTextOnFocus: PropTypes.bool,
/** /**
* If true, all text will automatically be selected on focus * If `true`, all text will automatically be selected on focus.
*/ */
selectTextOnFocus: PropTypes.bool, selectTextOnFocus: PropTypes.bool,
/** /**
* If true, the text field will blur when submitted. * If `true`, the text field will blur when submitted.
* The default value is true for single-line fields and false for * The default value is true for single-line fields and false for
* multiline fields. Note that for multiline fields, setting blurOnSubmit * multiline fields. Note that for multiline fields, setting `blurOnSubmit`
* to true means that pressing return will blur the field and trigger the * to `true` means that pressing return will blur the field and trigger the
* onSubmitEditing event instead of inserting a newline into the field. * `onSubmitEditin`g event instead of inserting a newline into the field.
*/ */
blurOnSubmit: PropTypes.bool, blurOnSubmit: PropTypes.bool,
/** /**
* Styles * [Styles](/react-native/docs/style.html)
*/ */
style: Text.propTypes.style, style: Text.propTypes.style,
/** /**
* The color of the textInput underline. * The color of the `TextInput` underline.
* @platform android * @platform android
*/ */
underlineColorAndroid: ColorPropType, underlineColorAndroid: ColorPropType,
@ -357,7 +435,7 @@ const TextInput = React.createClass({
{})) : Object), {})) : Object),
/** /**
* Returns if the input is currently focused. * Returns `true` if the input is currently focused; `false` otherwise.
*/ */
isFocused: function(): boolean { isFocused: function(): boolean {
return TextInputState.currentlyFocusedField() === return TextInputState.currentlyFocusedField() ===
@ -411,7 +489,7 @@ const TextInput = React.createClass({
}, },
/** /**
* Removes all text from the input. * Removes all text from the `TextInput`.
*/ */
clear: function() { clear: function() {
this.setNativeProps({text: ''}); this.setNativeProps({text: ''});