From 91134d16c9c1268de49a5b75a439a1543b5ad82c Mon Sep 17 00:00:00 2001 From: Joel Marcey Date: Fri, 24 Jun 2016 11:53:30 -0700 Subject: [PATCH] Update TextInput API 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 --- Libraries/Components/TextInput/TextInput.js | 212 +++++++++++++------- 1 file changed, 145 insertions(+), 67 deletions(-) diff --git a/Libraries/Components/TextInput/TextInput.js b/Libraries/Components/TextInput/TextInput.js index 2df8d27810..505fdea088 100644 --- a/Libraries/Components/TextInput/TextInput.js +++ b/Libraries/Components/TextInput/TextInput.js @@ -57,12 +57,29 @@ type Event = Object; * such as `onSubmitEditing` and `onFocus` that can be subscribed to. A simple * example: * - * ``` - * this.setState({text})} - * value={this.state.text} - * /> + * ```ReactNativeWebPlayer + * import React, { Component } from 'react'; + * import { AppRegistry, TextInput } from 'react-native'; + * + * class UselessTextInput extends Component { + * constructor(props) { + * super(props); + * this.state = { text: 'Useless Placeholder' }; + * } + * + * render() { + * return ( + * 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}`. @@ -71,10 +88,55 @@ type Event = Object; * `multiline=false`. To achieve the same effect, you can wrap your `TextInput` * in a `View`: * - * ``` - * - * - * + * ```ReactNativeWebPlayer + * import React, { Component } from 'react'; + * import { AppRegistry, View, TextInput } from 'react-native'; + * + * class UselessTextInput extends Component { + * render() { + * return ( + * + * ); + * } + * } + * + * 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 ( + * + * this.setState({text})} + * value={this.state.text} + * /> + * + * ); + * } + * } + * + * // App registration and rendering + * AppRegistry.registerComponent( + * 'AwesomeProject', + * () => UselessTextInputMultiline + * ); * ``` * * `TextInput` has by default a border at the bottom of its view. This border @@ -94,12 +156,12 @@ const TextInput = React.createClass({ propTypes: { ...View.propTypes, /** - * Can tell TextInput to automatically capitalize certain characters. + * Can tell `TextInput` to automatically capitalize certain characters. * - * - characters: all characters, - * - words: first letter of each word - * - sentences: first letter of each sentence (default) - * - none: don't auto capitalize anything + * - `characters`: all characters. + * - `words`: first letter of each word. + * - `sentences`: first letter of each sentence (*default*). + * - `none`: don't auto capitalize anything. */ autoCapitalize: PropTypes.oneOf([ 'none', @@ -108,16 +170,16 @@ const TextInput = React.createClass({ 'characters', ]), /** - * If false, disables auto-correct. The default value is true. + * If `false`, disables auto-correct. The default value is `true`. */ autoCorrect: PropTypes.bool, /** - * If true, focuses the input on componentDidMount. - * The default value is false. + * If `true`, focuses the input on `componentDidMount`. + * The default value is `false`. */ 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, /** @@ -125,9 +187,9 @@ const TextInput = React.createClass({ * * The following values work across platforms: * - * - default - * - numeric - * - email-address + * - `default` + * - `numeric` + * - `email-address` */ keyboardType: PropTypes.oneOf([ // Cross-platform @@ -158,27 +220,33 @@ const TextInput = React.createClass({ * Determines how the return key should look. On Android you can also use * `returnKeyLabel`. * + * *Cross platform* + * * The following values work across platforms: * - * - done - * - go - * - next - * - search - * - send + * - `done` + * - `go` + * - `next` + * - `search` + * - `send` + * + * *Android Only* * * The following values work on Android only: * - * - none - * - previous + * - `none` + * - `previous` + * + * *iOS Only* * * The following values work on iOS only: * - * - default - * - emergency-call - * - google - * - join - * - route - * - yahoo + * - `default` + * - `emergency-call` + * - `google` + * - `join` + * - `route` + * - `yahoo` */ returnKeyType: PropTypes.oneOf([ // Cross-platform @@ -209,28 +277,28 @@ const TextInput = React.createClass({ */ maxLength: PropTypes.number, /** - * Sets the number of lines for a TextInput. Use it with multiline set to - * true to be able to fill the lines. + * Sets the number of lines for a `TextInput`. Use it with multiline set to + * `true` to be able to fill the lines. * @platform android */ numberOfLines: PropTypes.number, /** - * 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. + * 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`. * @platform ios */ enablesReturnKeyAutomatically: PropTypes.bool, /** - * If true, the text input can be multiple lines. - * The default value is false. + * If `true`, the text input can be multiple lines. + * The default value is `false`. */ 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, /** - * Callback that is called when the text input is focused + * Callback that is called when the text input is focused. */ onFocus: PropTypes.func, /** @@ -247,18 +315,18 @@ const TextInput = React.createClass({ */ 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, /** * 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, /** * Callback that is called when a key is pressed. * Pressed key value is passed as an argument to the callback handler. - * Fires before onChange callbacks. + * Fires before `onChange` callbacks. * @platform ios */ onKeyPress: PropTypes.func, @@ -267,32 +335,42 @@ const TextInput = React.createClass({ */ 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, /** - * The text color of the placeholder string + * The text color of the placeholder string. */ placeholderTextColor: ColorPropType, /** - * If true, the text input obscures the text entered so that sensitive text - * like passwords stay secure. The default value is false. + * If `true`, the text input obscures the text entered so that sensitive text + * like passwords stay secure. The default value is `false`. */ 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, /** - * See DocumentSelectionState.js, some state that is responsible for - * maintaining selection information for a document + * An instance of `DocumentSelectionState`, this is some state that is responsible for + * 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 */ 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 - * 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 * by keeping value the same. In addition to simply setting the same value, * either set `editable={false}`, or set/update `maxLength` to prevent @@ -301,12 +379,12 @@ const TextInput = React.createClass({ value: PropTypes.string, /** * 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. */ 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 */ clearButtonMode: PropTypes.oneOf([ @@ -316,28 +394,28 @@ const TextInput = React.createClass({ 'always', ]), /** - * If true, clears the text field automatically when editing begins + * If `true`, clears the text field automatically when editing begins. * @platform ios */ 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, /** - * 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 - * multiline fields. Note that for multiline fields, setting blurOnSubmit - * to true means that pressing return will blur the field and trigger the - * onSubmitEditing event instead of inserting a newline into the field. + * multiline fields. Note that for multiline fields, setting `blurOnSubmit` + * to `true` means that pressing return will blur the field and trigger the + * `onSubmitEditin`g event instead of inserting a newline into the field. */ blurOnSubmit: PropTypes.bool, /** - * Styles + * [Styles](/react-native/docs/style.html) */ style: Text.propTypes.style, /** - * The color of the textInput underline. + * The color of the `TextInput` underline. * @platform android */ underlineColorAndroid: ColorPropType, @@ -357,7 +435,7 @@ const TextInput = React.createClass({ {})) : Object), /** - * Returns if the input is currently focused. + * Returns `true` if the input is currently focused; `false` otherwise. */ isFocused: function(): boolean { 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() { this.setNativeProps({text: ''});