From 41a20fd3ba09cfcfd3e96d5546c4b2c5bfde66ec Mon Sep 17 00:00:00 2001 From: Hector Ramos Date: Wed, 8 Nov 2017 17:35:11 -0800 Subject: [PATCH 1/4] Update markdown in flattened autodocs --- docs/accessibilityinfo.md | 10 +- docs/actionsheetios.md | 6 +- docs/activityindicator.md | 2 +- docs/alert.md | 2 +- docs/alertios.md | 26 +- docs/animated.md | 30 +- docs/appregistry.md | 20 +- docs/appstate.md | 43 +- docs/asyncstorage.md | 103 ++-- docs/backandroid.md | 8 +- docs/backhandler.md | 18 +- docs/cameraroll.md | 15 +- docs/checkbox.md | 2 +- docs/clipboard.md | 14 +- docs/custom-webview-android.md | 2 +- docs/datepickerandroid.md | 6 +- docs/datepickerios.md | 2 +- docs/dimensions.md | 29 +- docs/drawerlayoutandroid.md | 2 +- docs/flatlist.md | 542 +++++++++++++++--- docs/geolocation.md | 12 +- ...styleproptypes.md => image-style-props.md} | 43 +- docs/image.md | 97 +--- docs/imageeditor.md | 21 +- docs/imagepickerios.md | 8 +- docs/imagestore.md | 8 +- docs/interactionmanager.md | 8 +- docs/keyboard.md | 8 +- docs/keyboardavoidingview.md | 4 +- docs/layout-props.md | 2 +- docs/layoutanimation.md | 6 +- docs/linking.md | 16 +- docs/maskedviewios.md | 4 +- docs/modal.md | 2 +- docs/navigatorios.md | 130 +++-- docs/netinfo.md | 82 ++- docs/panresponder.md | 58 +- docs/permissionsandroid.md | 87 +-- docs/picker-item.md | 57 ++ docs/picker-style-props.md | 32 ++ docs/picker.md | 55 +- docs/pickerios.md | 7 +- docs/pixelratio.md | 46 +- docs/progressbarandroid.md | 16 +- docs/progressviewios.md | 2 +- docs/pushnotificationios.md | 77 ++- docs/refreshcontrol.md | 2 +- docs/scrollview.md | 39 +- docs/sectionlist.md | 376 ++++++++++-- docs/segmentedcontrolios.md | 2 +- docs/settings.md | 8 +- docs/shadow-props.md | 2 +- docs/share.md | 18 +- docs/slider.md | 14 +- docs/snapshotviewios.md | 3 +- docs/statusbar.md | 46 +- docs/statusbarios.md | 10 +- docs/stylesheet.md | 93 ++- docs/switch.md | 10 +- docs/systrace.md | 27 +- docs/tabbarios-item.md | 11 +- docs/tabbarios.md | 14 +- ...tstyleproptypes.md => text-style-props.md} | 46 +- docs/text.md | 1 + docs/textinput.md | 2 +- docs/timepickerandroid.md | 6 +- docs/toastandroid.md | 15 +- docs/toolbarandroid.md | 2 +- docs/touchablehighlight.md | 2 +- docs/touchablenativefeedback.md | 26 +- docs/touchablewithoutfeedback.md | 10 +- docs/vibration.md | 14 +- docs/vibrationios.md | 16 +- docs/{viewproptypes.md => view-props.md} | 70 +-- ...wstyleproptypes.md => view-style-props.md} | 62 +- docs/view.md | 19 +- docs/viewpagerandroid.md | 19 +- docs/virtualizedlist.md | 427 ++++++++++++-- docs/webview.md | 32 +- 79 files changed, 2134 insertions(+), 1080 deletions(-) rename docs/{imagestyleproptypes.md => image-style-props.md} (61%) create mode 100644 docs/picker-item.md create mode 100644 docs/picker-style-props.md rename docs/{textstyleproptypes.md => text-style-props.md} (67%) rename docs/{viewproptypes.md => view-props.md} (86%) rename docs/{viewstyleproptypes.md => view-style-props.md} (58%) diff --git a/docs/accessibilityinfo.md b/docs/accessibilityinfo.md index d85927eafc8040..d1d7625c21867f 100644 --- a/docs/accessibilityinfo.md +++ b/docs/accessibilityinfo.md @@ -78,7 +78,7 @@ class ScreenReaderStatusExample extends React.Component { ### `fetch()` ```javascript -static fetch() +AccessibilityInfo.fetch() ``` @@ -94,7 +94,7 @@ and `false` otherwise. ### `addEventListener()` ```javascript -static addEventListener(eventName, handler) +AccessibilityInfo.addEventListener(eventName, handler) ``` @@ -117,7 +117,7 @@ Add an event handler. Supported events: ### `setAccessibilityFocus()` ```javascript -static setAccessibilityFocus(reactTag) +AccessibilityInfo.setAccessibilityFocus(reactTag) ``` @@ -131,7 +131,7 @@ iOS-Only. Set accessibility focus to a react component. ### `announceForAccessibility()` ```javascript -static announceForAccessibility(announcement) +AccessibilityInfo.announceForAccessibility(announcement) ``` @@ -145,7 +145,7 @@ iOS-Only. Post a string to be announced by the screen reader. ### `removeEventListener()` ```javascript -static removeEventListener(eventName, handler) +AccessibilityInfo.removeEventListener(eventName, handler) ``` diff --git a/docs/actionsheetios.md b/docs/actionsheetios.md index 2d998d3f167c95..0f97351edd9331 100644 --- a/docs/actionsheetios.md +++ b/docs/actionsheetios.md @@ -8,7 +8,7 @@ next: alert previous: accessibilityinfo --- - +Display action sheets and share sheets on iOS. ### Methods @@ -27,7 +27,7 @@ previous: accessibilityinfo ### `showActionSheetWithOptions()` ```javascript -static showActionSheetWithOptions(options, callback) +ActionSheetIOS.showActionSheetWithOptions(options, callback) ``` @@ -65,7 +65,7 @@ ActionSheetIOS.showActionSheetWithOptions({ ### `showShareActionSheetWithOptions()` ```javascript -static showShareActionSheetWithOptions(options, failureCallback, successCallback) +ActionSheetIOS.showShareActionSheetWithOptions(options, failureCallback, successCallback) ``` diff --git a/docs/activityindicator.md b/docs/activityindicator.md index f00406d2911b00..4b6f22d9046ca6 100644 --- a/docs/activityindicator.md +++ b/docs/activityindicator.md @@ -51,7 +51,7 @@ AppRegistry.registerComponent('App', () => App) ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`animating`](docs/activityindicator.html#animating) - [`color`](docs/activityindicator.html#color) - [`size`](docs/activityindicator.html#size) diff --git a/docs/alert.md b/docs/alert.md index 87f67237581991..63de1f42d8bc9a 100644 --- a/docs/alert.md +++ b/docs/alert.md @@ -72,7 +72,7 @@ Alert.alert( ### `alert()` ```javascript -static alert(title, message?, buttons?, options?, type?) +Alert.alert(title, message?, buttons?, options?, type?) ``` diff --git a/docs/alertios.md b/docs/alertios.md index 7079e67bfde6ca..ffd4e51e08cd48 100644 --- a/docs/alertios.md +++ b/docs/alertios.md @@ -56,7 +56,7 @@ cross-platform support if you don't need to create iOS-only prompts. ### `alert()` ```javascript -static alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object] +AlertIOS.alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object] ``` Create and display a popup alert. @@ -65,10 +65,10 @@ Create and display a popup alert. | Name | Type | Required | Description | | - | - | - | - | -| title | string | No | The dialog's title. Passing null or '' will hide the title. | -| message | string | Yes | An optional message that appears below the dialog's title. | -| callbackOrButtons | ?(() => void),[ButtonsArray](docs/alertios.html#buttonsarray) | Yes | This optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a `text` key, as well as optional `onPress` and `style` keys. `style` should be one of 'default', 'cancel' or 'destructive'. | -| type | [AlertType](docs/alertios.html#alerttype) | Yes | Deprecated, do not use. | +| title | string | Yes | The dialog's title. Passing null or '' will hide the title. | +| message | string | No | An optional message that appears below the dialog's title. | +| callbackOrButtons | ?(() => void),[ButtonsArray](docs/alertios.html#buttonsarray) | No | This optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called when the user taps 'OK'. If passed an array of button configurations, each button should include a `text` key, as well as optional `onPress` and `style` keys. `style` should be one of 'default', 'cancel' or 'destructive'. | +| type | [AlertType](docs/alertios.html#alerttype) | No | Deprecated, do not use. | @@ -93,7 +93,7 @@ AlertIOS.alert( ### `prompt()` ```javascript -static prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object] +AlertIOS.prompt(title: string, [message]: string, [callbackOrButtons]: ?((text: string) => void), ButtonsArray, [type]: AlertType, [defaultValue]: string, [keyboardType]: string): [object Object] ``` Create and display a prompt to enter some text. @@ -102,12 +102,12 @@ Create and display a prompt to enter some text. | Name | Type | Required | Description | | - | - | - | - | -| title | string | No | The dialog's title. | -| message | string | Yes | An optional message that appears above the text input. | -| callbackOrButtons | ?((text: string) => void),[ButtonsArray](docs/alertios.html#buttonsarray) | Yes | This optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a `text` key, as well as optional `onPress` and `style` keys (see example). `style` should be one of 'default', 'cancel' or 'destructive'. | -| type | [AlertType](docs/alertios.html#alerttype) | Yes | This configures the text input. One of 'plain-text', 'secure-text' or 'login-password'. | -| defaultValue | string | Yes | The default text in text input. | -| keyboardType | string | Yes | The keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'. | +| title | string | Yes | The dialog's title. | +| message | string | No | An optional message that appears above the text input. | +| callbackOrButtons | ?((text: string) => void),[ButtonsArray](docs/alertios.html#buttonsarray) | No | This optional argument should be either a single-argument function or an array of buttons. If passed a function, it will be called with the prompt's value when the user taps 'OK'. If passed an array of button configurations, each button should include a `text` key, as well as optional `onPress` and `style` keys (see example). `style` should be one of 'default', 'cancel' or 'destructive'. | +| type | [AlertType](docs/alertios.html#alerttype) | No | This configures the text input. One of 'plain-text', 'secure-text' or 'login-password'. | +| defaultValue | string | No | The default text in text input. | +| keyboardType | string | No | The keyboard type of first text field(if exists). One of 'default', 'email-address', 'numeric', 'phone-pad', 'ascii-capable', 'numbers-and-punctuation', 'url', 'number-pad', 'name-phone-pad', 'decimal-pad', 'twitter' or 'web-search'. | @@ -191,7 +191,7 @@ An Alert button style ### ButtonsArray -Array or buttons +Array of buttons | Type | | - | diff --git a/docs/animated.md b/docs/animated.md index aa6b6ae915d17a..a18f4cb2857317 100644 --- a/docs/animated.md +++ b/docs/animated.md @@ -533,25 +533,51 @@ static unforkEvent(event, listener) ## Properties +### Value +Standard value class for driving animations. Typically initialized with `new Animated.Value(0);` ---- +See also `AnimatedValue.js`. +| Type | +| - | +| AnimatedValue | --- +### ValueXY +2D value class for driving 2D animations, such as pan gestures. ---- +See also `AnimatedValueXY.js`. + +| Type | +| - | +| AnimatedValueXY | --- +### Interpolation + +Exported to use the Interpolation type in flow + +See also `AnimatedInterpolation.js`. +| Type | +| - | +| AnimatedInterpolation | --- +### Node + +Exported for ease of type checking. All animated values derive from this class. + +| Type | +| - | +| AnimatedNode | diff --git a/docs/appregistry.md b/docs/appregistry.md index 83d119244601d6..81b5129441f520 100644 --- a/docs/appregistry.md +++ b/docs/appregistry.md @@ -199,12 +199,13 @@ static registerHeadlessTask(taskKey, task) Register a headless task. A headless task is a bit of code that runs without a UI. -@param taskKey the key associated with this task -@param task a promise returning function that takes some data passed from the native side as - the only argument; when the promise is resolved or rejected the native side is - notified of this event and it may decide to destroy the JS context. +**Parameters:** +| Name | Type | Required | Description | +| - | - | - | - | +| taskKey | string | No | The key associated with this task. | +| task | function | No | A promise returning function that takes some data passed from the native side as the only argument; when the promise is resolved or rejected the native side is notified of this event and it may decide to destroy the JS context. | --- @@ -215,12 +216,15 @@ Register a headless task. A headless task is a bit of code that runs without a U static startHeadlessTask(taskId, taskKey, data) ``` - Only called from native code. Starts a headless task. -@param taskId the native id for this task instance to keep track of its execution -@param taskKey the key for the task to start -@param data the data to pass to the task +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| taskId | number | No | The native id for this task instance to keep track of its execution | +| taskKey | string | No | The key for the task to start | +| data | any | No | The data to pass to the task | diff --git a/docs/appstate.md b/docs/appstate.md index ee208e3d0f9906..efe0e1274d33a2 100644 --- a/docs/appstate.md +++ b/docs/appstate.md @@ -16,23 +16,18 @@ handling push notifications. ### App States - - `active` - The app is running in the foreground - - `background` - The app is running in the background. The user is either - in another app or on the home screen - - `inactive` - This is a state that occurs when transitioning between - foreground & background, and during periods of inactivity such as - entering the Multitasking view or in the event of an incoming call +- `active` - The app is running in the foreground +- `background` - The app is running in the background. The user is either + in another app or on the home screen +- `inactive` - This is a state that occurs when transitioning between foreground & background, and during periods of inactivity such as entering the Multitasking view or in the event of an incoming call -For more information, see -[Apple's documentation](https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html) +For more information, see [Apple's documentation](https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/TheAppLifeCycle/TheAppLifeCycle.html) ### Basic Usage -To see the current state, you can check `AppState.currentState`, which -will be kept up-to-date. However, `currentState` will be null at launch -while `AppState` retrieves it over the bridge. +To see the current state, you can check `AppState.currentState`, which will be kept up-to-date. However, `currentState` will be null at launch while `AppState` retrieves it over the bridge. -``` +```javascript import React, {Component} from 'react' import {AppState, Text} from 'react-native' @@ -66,14 +61,11 @@ class AppStateExample extends Component { } ``` -This example will only ever appear to say "Current state is: active" because -the app is only visible to the user when in the `active` state, and the null -state will happen only momentarily. +This example will only ever appear to say "Current state is: active" because the app is only visible to the user when in the `active` state, and the null state will happen only momentarily. ### Methods -- [`=`](docs/appstate.html#) - [`addEventListener`](docs/appstate.html#addeventlistener) - [`removeEventListener`](docs/appstate.html#removeeventlistener) @@ -86,16 +78,6 @@ state will happen only momentarily. ## Methods -### `=()` - -```javascript -=(;, () -``` - - - ---- - ### `addEventListener()` ```javascript @@ -106,15 +88,6 @@ addEventListener(type, handler) Add a handler to AppState changes by listening to the `change` event type and providing the handler -TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate -`addEventListener` and `removeEventListener` and just use `addListener` and -`listener.remove()` directly. That will be a breaking change though, as both -the method and event names are different (addListener events are currently -required to be globally unique). - - - - --- ### `removeEventListener()` diff --git a/docs/asyncstorage.md b/docs/asyncstorage.md index 2a88f2d47d0b1e..01c18672285dc4 100644 --- a/docs/asyncstorage.md +++ b/docs/asyncstorage.md @@ -7,24 +7,17 @@ permalink: docs/asyncstorage.html next: backandroid previous: appstate --- -`AsyncStorage` is a simple, unencrypted, asynchronous, persistent, key-value storage -system that is global to the app. It should be used instead of LocalStorage. +`AsyncStorage` is a simple, unencrypted, asynchronous, persistent, key-value storage system that is global to the app. It should be used instead of LocalStorage. -It is recommended that you use an abstraction on top of `AsyncStorage` -instead of `AsyncStorage` directly for anything more than light usage since -it operates globally. +It is recommended that you use an abstraction on top of `AsyncStorage` instead of `AsyncStorage` directly for anything more than light usage since it operates globally. -On iOS, `AsyncStorage` is backed by native code that stores small values in a -serialized dictionary and larger values in separate files. On Android, -`AsyncStorage` will use either [RocksDB](http://rocksdb.org/) or SQLite -based on what is available. +On iOS, `AsyncStorage` is backed by native code that stores small values in a serialized dictionary and larger values in separate files. On Android, `AsyncStorage` will use either [RocksDB](http://rocksdb.org/) or SQLite based on what is available. -The `AsyncStorage` JavaScript code is a simple facade that provides a clear -JavaScript API, real `Error` objects, and simple non-multi functions. Each -method in the API returns a `Promise` object. +The `AsyncStorage` JavaScript code is a simple facade that provides a clear JavaScript API, real `Error` objects, and simple non-multi functions. Each method in the API returns a `Promise` object. Persisting data: -``` + +```javascript try { await AsyncStorage.setItem('@MySuperStore:key', 'I like to save it.'); } catch (error) { @@ -33,7 +26,8 @@ try { ``` Fetching data: -``` + +```javascript try { const value = await AsyncStorage.getItem('@MySuperStore:key'); if (value !== null){ @@ -53,6 +47,11 @@ try { - [`mergeItem`](docs/asyncstorage.html#mergeitem) - [`clear`](docs/asyncstorage.html#clear) - [`getAllKeys`](docs/asyncstorage.html#getallkeys) + +The following batched functions are useful for executing a lot of operations at once, allowing for native optimizations and provide the convenience of a single callback after all operations are complete. + +These functions return arrays of errors, potentially one for every key. For key-specific errors, the Error object will have a key property to indicate which key caused the error. + - [`flushGetRequests`](docs/asyncstorage.html#flushgetrequests) - [`multiGet`](docs/asyncstorage.html#multiget) - [`multiSet`](docs/asyncstorage.html#multiset) @@ -81,8 +80,8 @@ Returns a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| key | string | No | Key of the item to fetch. | -| callback | ?(error: ?Error, result: ?string) => void | Yes | Function that will be called with a result if found or any error. | +| key | string | Yes | Key of the item to fetch. | +| callback | ?(error: ?Error, result: ?string) => void | No | Function that will be called with a result if found or any error. | @@ -95,16 +94,17 @@ Returns a `Promise` object. static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void) ``` -Sets the value for a `key` and invokes a callback upon completion. +Sets the value for a `key` and invokes a callback upon completion. + Returns a `Promise` object. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| key | string | No | Key of the item to set. | -| value | string | No | Value to set for the `key`. | -| callback | ?(error: ?Error) => void | Yes | Function that will be called with any error. | +| key | string | Yes | Key of the item to set. | +| value | string | Yes | Value to set for the `key`. | +| callback | ?(error: ?Error) => void | No | Function that will be called with any error. | @@ -124,8 +124,8 @@ Returns a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| key | string | No | Key of the item to remove. | -| callback | ?(error: ?Error) => void | Yes | Function that will be called with any error. | +| key | string | Yes | Key of the item to remove. | +| callback | ?(error: ?Error) => void | No | Function that will be called with any error. | @@ -138,35 +138,32 @@ Returns a `Promise` object. static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void) ``` -Merges an existing `key` value with an input value, assuming both values -are stringified JSON. Returns a `Promise` object. +Merges an existing `key` value with an input value, assuming both values are stringified JSON. Returns a `Promise` object. -**NOTE:** This is not supported by all native implementations. +> Note: +> This is not supported by all native implementations. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| key | string | No | Key of the item to modify. | -| value | string | No | New value to merge for the `key`. | -| callback | ?(error: ?Error) => void | Yes | Function that will be called with any error. | - - +| key | string | Yes | Key of the item to modify. | +| value | string | Yes | New value to merge for the `key`. | +| callback | ?(error: ?Error) => void | No | Function that will be called with any error. | Example: ```javascript - let UID123_object = { - name: 'Chris', - age: 30, - traits: {hair: 'brown', eyes: 'brown'}, + name: 'Chris', + age: 30, + traits: {hair: 'brown', eyes: 'brown'}, }; // You only need to define what will be added or updated let UID123_delta = { - age: 31, - traits: {eyes: 'blue', shoe_size: 10} + age: 31, + traits: {eyes: 'blue', shoe_size: 10} }; AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => { @@ -182,8 +179,6 @@ AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => { // {'shoe_size':10,'hair':'brown','eyes':'blue'}} ``` - - --- ### `clear()` @@ -192,15 +187,13 @@ AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => { static clear([callback]: ?(error: ?Error) => void) ``` -Erases *all* `AsyncStorage` for all clients, libraries, etc. You probably -don't want to call this; use `removeItem` or `multiRemove` to clear only -your app's keys. Returns a `Promise` object. +Erases *all* `AsyncStorage` for all clients, libraries, etc. You probably don't want to call this; use `removeItem` or `multiRemove` to clear only your app's keys. Returns a `Promise` object. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| callback | ?(error: ?Error) => void | Yes | Function that will be called with any error. | +| callback | ?(error: ?Error) => void | No | Function that will be called with any error. | @@ -220,7 +213,7 @@ Returns a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| callback | ?(error: ?Error, keys: ?Array) => void | Yes | Function that will be called the keys found and any error. | +| callback | ?(error: ?Error, keys: ?Array) => void | No | Function that will be called the keys found and any error. | @@ -235,8 +228,6 @@ static flushGetRequests(): [object Object] Flushes any pending requests using a single batch call to get the data. - - --- ### `multiGet()` @@ -245,9 +236,7 @@ Flushes any pending requests using a single batch call to get the data. static multiGet(keys: Array, [callback]: ?(errors: ?Array, result: ?Array>) => void) ``` -This allows you to batch the fetching of items given an array of `key` -inputs. Your callback will be invoked with an array of corresponding -key-value pairs found: +This allows you to batch the fetching of items given an array of `key` inputs. Your callback will be invoked with an array of corresponding key-value pairs found: ``` multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']]) @@ -259,10 +248,8 @@ The method returns a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| keys | Array | No | Array of key for the items to get. | -| callback | ?(errors: ?Array, result: ?Array>) => void | Yes | Function that will be called with a key-value array of the results, plus an array of any key-specific errors found. | - - +| keys | Array | Yes | Array of key for the items to get. | +| callback | ?(errors: ?Array, result: ?Array>) => void | No | Function that will be called with a key-value array of the results, plus an array of any key-specific errors found. | Example: @@ -302,8 +289,8 @@ The method returns a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| keyValuePairs | Array> | No | Array of key-value array for the items to set. | -| callback | ?(errors: ?Array) => void | Yes | Function that will be called with an array of any key-specific errors found. | +| keyValuePairs | Array> | Yes | Array of key-value array for the items to set. | +| callback | ?(errors: ?Array) => void | No | Function that will be called with an array of any key-specific errors found. | @@ -323,8 +310,8 @@ a `Promise` object. | Name | Type | Required | Description | | - | - | - | - | -| keys | Array | No | Array of key for the items to delete. | -| callback | ?(errors: ?Array) => void | Yes | Function that will be called an array of any key-specific errors found. | +| keys | Array | Yes | Array of key for the items to delete. | +| callback | ?(errors: ?Array) => void | No | Function that will be called an array of any key-specific errors found. | @@ -360,8 +347,8 @@ keys. This assumes that the values are stringified JSON. Returns a | Name | Type | Required | Description | | - | - | - | - | -| keyValuePairs | Array> | No | Array of key-value array for the items to merge. | -| callback | ?(errors: ?Array) => void | Yes | Function that will be called with an array of any key-specific errors found. | +| keyValuePairs | Array> | Yes | Array of key-value array for the items to merge. | +| callback | ?(errors: ?Array) => void | No | Function that will be called with an array of any key-specific errors found. | diff --git a/docs/backandroid.md b/docs/backandroid.md index 0ee553c67bc16c..0dd040cd3525c7 100644 --- a/docs/backandroid.md +++ b/docs/backandroid.md @@ -8,7 +8,7 @@ next: backhandler previous: asyncstorage --- -Deprecated. Use BackHandler instead. +**Deprecated.** Use [BackHandler](docs/backhandler.html) instead. ### Methods @@ -29,7 +29,7 @@ Deprecated. Use BackHandler instead. ### `exitApp()` ```javascript -static exitApp() +BackAndroid.exitApp() ``` @@ -39,7 +39,7 @@ static exitApp() ### `addEventListener()` ```javascript -static addEventListener(eventName, handler) +BackAndroid.addEventListener(eventName, handler) ``` @@ -49,7 +49,7 @@ static addEventListener(eventName, handler) ### `removeEventListener()` ```javascript -static removeEventListener(eventName, handler) +BackAndroid.removeEventListener(eventName, handler) ``` diff --git a/docs/backhandler.md b/docs/backhandler.md index 890a9325ca6ca6..57f2a8b9e46805 100644 --- a/docs/backhandler.md +++ b/docs/backhandler.md @@ -10,17 +10,13 @@ previous: backhandler Detect hardware button presses for back navigation. -Android: Detect hardware back button presses, and programmatically invoke the default back button -functionality to exit the app if there are no listeners or if none of the listeners return true. +**Android:** Detect hardware back button presses, and programmatically invoke the default back button functionality to exit the app if there are no listeners or if none of the listeners return true. -tvOS: Detect presses of the menu button on the TV remote. (Still to be implemented: -programmatically disable menu button handling -functionality to exit the app if there are no listeners or if none of the listeners return true.) +**tvOS:** Detect presses of the menu button on the TV remote. Still to be implemented: programmatically disable menu button handling functionality to exit the app if there are no listeners or if none of the listeners return true. -iOS: Not applicable. +**iOS:** Not applicable. -The event subscriptions are called in reverse order (i.e. last registered subscription first), -and if one subscription returns true then subscriptions registered earlier will not be called. +The event subscriptions are called in reverse order (i.e. last registered subscription first), and if one subscription returns true then subscriptions registered earlier will not be called. Example: @@ -56,7 +52,7 @@ BackHandler.addEventListener('hardwareBackPress', function() { ### `exitApp()` ```javascript -static exitApp() +BackHandler.exitApp() ``` @@ -66,7 +62,7 @@ static exitApp() ### `addEventListener()` ```javascript -static addEventListener(eventName, handler) +BackHandler.addEventListener(eventName, handler) ``` @@ -76,7 +72,7 @@ static addEventListener(eventName, handler) ### `removeEventListener()` ```javascript -static removeEventListener(eventName, handler) +BackHandler.removeEventListener(eventName, handler) ``` diff --git a/docs/cameraroll.md b/docs/cameraroll.md index 15741c80375f8c..127aecd7cbeb6f 100644 --- a/docs/cameraroll.md +++ b/docs/cameraroll.md @@ -21,7 +21,6 @@ app will use this data. This key will appear as `Privacy - Photo Library Usage D ### Methods -- [`=`](docs/cameraroll.html#) - [`saveToCameraRoll`](docs/cameraroll.html#savetocameraroll) - [`getPhotos`](docs/cameraroll.html#getphotos) @@ -34,20 +33,10 @@ app will use this data. This key will appear as `Privacy - Photo Library Usage D ## Methods -### `=()` - -```javascript -=(;, AssetTypeOptions, static, (, :) -``` - - - ---- - ### `saveToCameraRoll()` ```javascript -static saveToCameraRoll(tag, type?) +CameraRoll.saveToCameraRoll(tag, type?) ``` @@ -72,7 +61,7 @@ Returns a Promise which will resolve with the new URI. ### `getPhotos()` ```javascript -static getPhotos(params) +CameraRoll.getPhotos(params) ``` diff --git a/docs/checkbox.md b/docs/checkbox.md index 100d67434b6bb4..679b5df885a98c 100644 --- a/docs/checkbox.md +++ b/docs/checkbox.md @@ -19,7 +19,7 @@ the supplied `value` prop instead of the expected result of any user actions. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`disabled`](docs/checkbox.html#disabled) - [`onChange`](docs/checkbox.html#onchange) - [`onValueChange`](docs/checkbox.html#onvaluechange) diff --git a/docs/clipboard.md b/docs/clipboard.md index 5d6dd7af1e1ec4..47a9e3488359dd 100644 --- a/docs/clipboard.md +++ b/docs/clipboard.md @@ -28,7 +28,7 @@ previous: cameraroll ### `getString()` ```javascript -static getString() +Clipboard.getString() ``` @@ -47,17 +47,23 @@ async _getContent() { ### `setString()` ```javascript -static setString(content) +Clipboard.setString(content) ``` -Set content of string type. You can use following code to set clipboard content +Set content of string type. You can use following code to set clipboard content: + ```javascript _setContent() { Clipboard.setString('hello world'); } ``` -@param the content to be stored in the clipboard. + +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| content | string | yes | The content to be stored in the clipboard. | diff --git a/docs/custom-webview-android.md b/docs/custom-webview-android.md index f3dcf7e76f24ce..05e0e30a951647 100644 --- a/docs/custom-webview-android.md +++ b/docs/custom-webview-android.md @@ -213,7 +213,7 @@ For events, the event handler must always be set to a function. This means it is If you are unsure how something should be implemented from the JS side, look at [WebView.android.js](https://github.com/facebook/react-native/blob/master/Libraries/Components/WebView/WebView.android.js) in the React Native source. -```js +```javascript export default class CustomWebView extends Component { static propTypes = { ...WebView.propTypes, diff --git a/docs/datepickerandroid.md b/docs/datepickerandroid.md index 7b16e10c166ee1..55f2819f6d239f 100644 --- a/docs/datepickerandroid.md +++ b/docs/datepickerandroid.md @@ -46,7 +46,7 @@ try { ### `open()` ```javascript -static open(options) +DatePickerAndroid.open(options) ``` @@ -78,7 +78,7 @@ when using the `minDate` and `maxDate` options. ### `dateSetAction()` ```javascript -static dateSetAction() +DatePickerAndroid.dateSetAction() ``` @@ -92,7 +92,7 @@ A date has been selected. ### `dismissedAction()` ```javascript -static dismissedAction() +DatePickerAndroid.dismissedAction() ``` diff --git a/docs/datepickerios.md b/docs/datepickerios.md index 60c6dc70bc8972..43795a3321d6f6 100644 --- a/docs/datepickerios.md +++ b/docs/datepickerios.md @@ -15,7 +15,7 @@ source of truth. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`date`](docs/datepickerios.html#date) - [`onDateChange`](docs/datepickerios.html#ondatechange) - [`maximumDate`](docs/datepickerios.html#maximumdate) diff --git a/docs/dimensions.md b/docs/dimensions.md index 4e57aaf445598c..65db7d95ecf4ca 100644 --- a/docs/dimensions.md +++ b/docs/dimensions.md @@ -29,14 +29,18 @@ previous: datepickerandroid ### `set()` ```javascript -static set(dims) +Dimensions.set(dims) ``` This should only be called from native code by sending the didUpdateDimensions event. -@param {object} dims Simple string-keyed object of dimensions to set +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| dims | object | Yes | Simple string-keyed object of dimensions to set | @@ -46,23 +50,24 @@ didUpdateDimensions event. ### `get()` ```javascript -static get(dim) +Dimensions.get(dim) ``` Initial dimensions are set before `runApplication` is called so they should be available before any other require's are run, but may be updated later. -Note: Although dimensions are available immediately, they may change (e.g -due to device rotation) so any rendering logic or styles that depend on -these constants should try to call this function on every render, rather -than caching the value (for example, using inline styles rather than -setting a value in a `StyleSheet`). +> Note: +> Although dimensions are available immediately, they may change (e.g due to device rotation) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value (for example, using inline styles rather than setting a value in a `StyleSheet`). Example: `var {height, width} = Dimensions.get('window');` -@param {string} dim Name of dimension as defined when calling `set`. -@returns {Object?} Value for the dimension. +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| dim | string | Yes | Name of dimension as defined when calling `set`. | + @@ -72,7 +77,7 @@ Example: `var {height, width} = Dimensions.get('window');` ### `addEventListener()` ```javascript -static addEventListener(type, handler) +Dimensions.addEventListener(type, handler) ``` @@ -91,7 +96,7 @@ Add an event handler. Supported events: ### `removeEventListener()` ```javascript -static removeEventListener(type, handler) +Dimensions.removeEventListener(type, handler) ``` diff --git a/docs/drawerlayoutandroid.md b/docs/drawerlayoutandroid.md index b9ae9809148ce6..0a2a393f0635f3 100644 --- a/docs/drawerlayoutandroid.md +++ b/docs/drawerlayoutandroid.md @@ -39,7 +39,7 @@ render: function() { ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`renderNavigationView`](docs/drawerlayoutandroid.html#rendernavigationview) - [`onDrawerClose`](docs/drawerlayoutandroid.html#ondrawerclose) - [`drawerPosition`](docs/drawerlayoutandroid.html#drawerposition) diff --git a/docs/flatlist.md b/docs/flatlist.md index 6ab1309ccd0039..617363de60e20a 100644 --- a/docs/flatlist.md +++ b/docs/flatlist.md @@ -23,10 +23,12 @@ If you need section support, use [``](docs/sectionlist.html). Minimal Example: +```javascript {item.key}} /> +``` More complex, multi-select example demonstrating `PureComponent` usage for perf optimization and avoiding bugs. @@ -39,87 +41,101 @@ More complex, multi-select example demonstrating `PureComponent` usage for perf not show any changes. - `keyExtractor` tells the list to use the `id`s for the react keys instead of the default `key` property. +```javascript +class MyListItem extends React.PureComponent { + _onPress = () => { + this.props.onPressItem(this.props.id); + }; + + render() { + const textColor = this.props.selected ? "red" : "black"; + return ( + + + + {this.props.title} + + + + ); + } +} + +class MultiSelectList extends React.PureComponent { + state = {selected: (new Map(): Map)}; + + _keyExtractor = (item, index) => item.id; + + _onPressItem = (id: string) => { + // updater functions are preferred for transactional updates + this.setState((state) => { + // copy the map rather than modifying state. + const selected = new Map(state.selected); + selected.set(id, !selected.get(id)); // toggle + return {selected}; + }); + }; + + _renderItem = ({item}) => ( + + ); + + render() { + return ( + + ); + } +} +``` - class MyListItem extends React.PureComponent { - _onPress = () => { - this.props.onPressItem(this.props.id); - }; - - render() { - const textColor = this.props.selected ? "red" : "black"; - return ( - - - - {this.props.title} - - - - ); - } - } - - class MultiSelectList extends React.PureComponent { - state = {selected: (new Map(): Map)}; - - _keyExtractor = (item, index) => item.id; - - _onPressItem = (id: string) => { - // updater functions are preferred for transactional updates - this.setState((state) => { - // copy the map rather than modifying state. - const selected = new Map(state.selected); - selected.set(id, !selected.get(id)); // toggle - return {selected}; - }); - }; - - _renderItem = ({item}) => ( - - ); - - render() { - return ( - - ); - } - } - -This is a convenience wrapper around [``](docs/virtualizedlist.html), -and thus inherits its props (as well as those of `ScrollView`) that aren't explicitly listed -here, along with the following caveats: - -- Internal state is not preserved when content scrolls out of the render window. Make sure all - your data is captured in the item data or external stores like Flux, Redux, or Relay. -- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- - equal. Make sure that everything your `renderItem` function depends on is passed as a prop - (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on - changes. This includes the `data` prop and parent component state. -- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously - offscreen. This means it's possible to scroll faster than the fill rate ands momentarily see - blank content. This is a tradeoff that can be adjusted to suit the needs of each application, - and we are working on improving it behind the scenes. -- By default, the list looks for a `key` prop on each item and uses that for the React key. - Alternatively, you can provide a custom `keyExtractor` prop. - -Also inherits [ScrollView Props](docs/scrollview.html#props), unless it is nested in another FlatList of same orientation. - -### Props +This is a convenience wrapper around [`VirtualizedList`](docs/virtualizedlist.html), and thus inherits its props (as well as those of `ScrollView`) that aren't explicitly listed here, along with the following caveats: -- [`numColumns`](docs/flatlist.html#numcolumns) +- Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay. +- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- equal. Make sure that everything your `renderItem` function depends on is passed as a prop (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on changes. This includes the `data` prop and parent component state. +- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate ands momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes. +- By default, the list looks for a `key` prop on each item and uses that for the React key. Alternatively, you can provide a custom `keyExtractor` prop. +Also inherits [ScrollView props](docs/scrollview.html#props), unless it is nested in another `FlatList` of same orientation. +### Props +- [`ScrollView` props...](docs/scrollview.html#props) +- [`VirtualizedList` props...](docs/virtualizedlist.html#props) +- [`renderItem`](docs/flatlist.html#renderitem) +- [`data`](docs/flatlist.html#data) +- [`ItemSeparatorComponent`](docs/flatlist.html#itemseparatorcomponent) +- [`ListEmptyComponent`](docs/flatlist.html#listemptycomponent) +- [`ListFooterComponent`](docs/flatlist.html#listgootercomponent) +- [`ListHeaderComponent`](docs/flatlist.html#listheadercomponent) +- [`columnwrapperstyle`](docs/flatlist.html#columnwrapperstyle) +- [`extraData`](docs/flatlist.html#extradata) +- [`getItemLayout`](docs/flatlist.html#getitemlayout) +- [`horizontal`](docs/flatlist.html#horizontal) +- [`initialNumToRender`](docs/flatlist.html#initialnumtorender) +- [`initialScrollIndex`](docs/flatlist.html#initialscrollindex) +- [`inverted`](docs/flatlist.html#inverted) +- [`keyExtractor`](docs/flatlist.html#keyextractor) +- [`numColumns`](docs/flatlist.html#numcolumns) +- [`onEndReached`](docs/flatlist.html#onendreached) +- [`onEndReachedThreshold`](docs/flatlist.html#onendreachedthreshold) +- [`onRefresh`](docs/flatlist.html#onrefresh) +- [`onViewableItemsChanged`](docs/flatlist.html#onviewableitemschanged) +- [`progressViewOffset`](docs/flatlist.html#progressviewoffset) +- [`legacyImplementation`](docs/flatlist.html#legacyimplementation) +- [`refreshing`](docs/flatlist.html#refreshing) +- [`removeClippedSubviews`](docs/flatlist.html#removeclippedsubviews) +- [`viewabilityConfig`](docs/flatlist.html#viewabilityconfig) +- [`viewabilityConfigCallbackPairs`](docs/flatlist.html#viewabilityconfigcallbackpairs) ### Methods @@ -145,18 +161,390 @@ Also inherits [ScrollView Props](docs/scrollview.html#props), unless it is neste ## Props +### `renderItem` + +```javascript +renderItem({ item: object, index: number, separators: { highlight: function, unhighlight: function, updateProps: function(select: string, newProps: object) } }): [element] +``` + +Takes an item from `data` and renders it into the list. + +Provides additional metadata like `index` if you need it, as well as a more generic `separators.updateProps` function which let's you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common `highlight` and `unhighlight` (which set the `highlighted: boolean` prop) are insufficient for your use case. + +| Type | Required | +| - | - | +| function | Yes | + + +Example usage: + +```javascript + ( + + )} + data={[{title: 'Title Text', key: 'item1'}]} + renderItem={({item, separators}) => ( + this._onPress(item)} + onShowUnderlay={separators.highlight} + onHideUnderlay={separators.unhighlight}> + + {item.title} + + + )} + /> +``` + + +--- + + +### `data` + +For simplicity, data is just a plain array. If you want to use something else, like an immutable list, use the underlying [`VirtualizedList`](docs/virtualizedlist.html) directly. + +| Type | Required | +| - | - | +| array | Yes | + + + +--- + + +### `ItemSeparatorComponent` + +Rendered in between each item, but not at the top or bottom. By default, `highlighted` and `leadingItem` props are provided. `renderItem` provides `separators.highlight`/`unhighlight` which will update the `highlighted` prop, but you can also add custom props with `separators.updateProps`. + +| Type | Required | +| - | - | +| component | No | + + + +--- + + +### `ListEmptyComponent` + +Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `ListFooterComponent` + +Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `ListHeaderComponent` + +Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `columnWrapperStyle` + +Optional custom style for multi-item rows generated when `numColumns > 1`. + +| Type | Required | +| - | - | +| style object | No | + + + +--- + + +### `extraData` + +A marker property for telling the list to re-render (since it implements `PureComponent`). If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop, stick it here and treat it immutably. + +| Type | Required | +| - | - | +| any | No | + + + + +--- + + +### `getItemLayout` + +```javascript +(data, index) => {length: number, offset: number, index: number} +``` + +`getItemLayout` is an optional optimization that let us skip measurement of dynamic content if you know the height of items a priori. `getItemLayout` is the most efficient, and is easy to use if you have fixed height items, for example: + +```javascript + getItemLayout={(data, index) => ( + {length: ITEM_HEIGHT, offset: ITEM_HEIGHT * index, index} + )} +``` + +Adding `getItemLayout` can be a great performance boost for lists of several hundred items. Remember to include separator length (height or width) in your offset calculation if you specify `ItemSeparatorComponent`. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `horizontal` + +If true, renders items next to each other horizontally instead of stacked vertically. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `initialNumToRender` + +How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions. + +| Type | Required | +| - | - | +| number | No | + + + +--- + + +### `initialScrollIndex` + +Instead of starting at the top with the first item, start at `initialScrollIndex`. This disables the "scroll to top" optimization that keeps the first `initialNumToRender` items always rendered and immediately renders the items starting at this initial index. Requires `getItemLayout` to be implemented. + +| Type | Required | +| - | - | +| number | No | + + + +--- + + +### `inverted` + +Reverses the direction of scroll. Uses scale transforms of `-1`. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `keyExtractor` + +```javascript +(item: object, index: number) => string +``` + +Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks `item.key`, then falls back to using the index, like React does. + +| Type | Required | +| - | - | +| function | No | + + + + +--- + + ### `numColumns` +Multiple columns can only be rendered with `horizontal={false}` and will zig-zag like a `flexWrap` layout. Items should all be the same height - masonry layouts are not supported. +| Type | Required | +| - | - | +| number | No | + + + + +--- + + +### `onEndReached` + +```javascript +(info: {distanceFromEnd: number}) => void +``` + +Called once when the scroll position gets within `onEndReachedThreshold` of the rendered content. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `onEndReachedThreshold` + + How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the `onEndReached` callback. Thus a value of 0.5 will trigger `onEndReached` when the end of the content is within half the visible length of the list. | Type | Required | | - | - | -| | No | +| number | No | +--- +### `onRefresh` + +```javascript +() => void +``` + +If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the `refreshing` prop correctly. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `onViewableItemsChanged` + +```javascript +(info: { + viewableItems: array, + changed: array, + }) => void +``` + +Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `progressViewOffset` + +Set this when offset is needed for the loading indicator to show correctly. + +| Type | Required | Platform | +| - | - | - | +| number | No | Android | + + + +--- + + +### `legacyImplementation` + +May not have full feature parity and is meant for debugging and performance comparison. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `refreshing` + +Set this true while waiting for new data from a refresh. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `removeClippedSubviews` + +This may improve scroll performance for large lists. + +> Note: +> May have bugs (missing content) in some circumstances - use at your own risk. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `viewabilityConfig` + +See `ViewabilityHelper.js` for flow type and further documentation. + +| Type | Required | +| - | - | +| ViewabilityConfig | No | + + + +--- + + +### `viewabilityConfigCallbackPairs` + +List of `ViewabilityConfig`/`onViewableItemsChanged` pairs. A specific `onViewableItemsChanged` will be called when its corresponding `ViewabilityConfig`'s conditions are met. See `ViewabilityHelper.js` for flow type and further documentation. + +| Type | Required | +| - | - | +| array of ViewabilityConfigCallbackPair | No | + ## Methods diff --git a/docs/geolocation.md b/docs/geolocation.md index 09bb454687d037..ab83e0d54637f9 100644 --- a/docs/geolocation.md +++ b/docs/geolocation.md @@ -74,7 +74,7 @@ was created from a mock provider. ### `setRNConfiguration()` ```javascript -static setRNConfiguration(config) +Geolocation.setRNConfiguration(config) ``` @@ -96,7 +96,7 @@ before using Geolocation APIs. ### `requestAuthorization()` ```javascript -static requestAuthorization() +Geolocation.requestAuthorization() ``` @@ -113,7 +113,7 @@ authorization. ### `getCurrentPosition()` ```javascript -static getCurrentPosition(geo_success, geo_error?, geo_options?) +Geolocation.getCurrentPosition(geo_success, geo_error?, geo_options?) ``` @@ -130,7 +130,7 @@ or it will request an update which might take a while. ### `watchPosition()` ```javascript -static watchPosition(success, error?, options?) +Geolocation.watchPosition(success, error?, options?) ``` @@ -145,7 +145,7 @@ options: timeout (ms), maximumAge (ms), enableHighAccuracy (bool), distanceFilte ### `clearWatch()` ```javascript -static clearWatch(watchID) +Geolocation.clearWatch(watchID) ``` @@ -155,7 +155,7 @@ static clearWatch(watchID) ### `stopObserving()` ```javascript -static stopObserving() +Geolocation.stopObserving() ``` diff --git a/docs/imagestyleproptypes.md b/docs/image-style-props.md similarity index 61% rename from docs/imagestyleproptypes.md rename to docs/image-style-props.md index eaac32b31f1ee9..1aff1d5091cc14 100644 --- a/docs/imagestyleproptypes.md +++ b/docs/image-style-props.md @@ -1,31 +1,34 @@ --- -id: imagestyleproptypes -title: ImageStylePropTypes +id: image-style-props +title: Image Style Props layout: docs category: APIs -permalink: docs/imagestyleproptypes.html +permalink: docs/image-style-props.html next: null -previous: textstyleproptypes +previous: text-style-props --- -### Props - -- [`borderTopRightRadius`](docs/imagestyleproptypes.html#bordertoprightradius) -- [`backfaceVisibility`](docs/imagestyleproptypes.html#backfacevisibility) -- [`borderBottomLeftRadius`](docs/imagestyleproptypes.html#borderbottomleftradius) -- [`borderBottomRightRadius`](docs/imagestyleproptypes.html#borderbottomrightradius) -- [`borderColor`](docs/imagestyleproptypes.html#bordercolor) -- [`borderRadius`](docs/imagestyleproptypes.html#borderradius) -- [`borderTopLeftRadius`](docs/imagestyleproptypes.html#bordertopleftradius) -- [`backgroundColor`](docs/imagestyleproptypes.html#backgroundcolor) -- [`borderWidth`](docs/imagestyleproptypes.html#borderwidth) -- [`opacity`](docs/imagestyleproptypes.html#opacity) -- [`overflow`](docs/imagestyleproptypes.html#overflow) -- [`resizeMode`](docs/imagestyleproptypes.html#resizemode) -- [`tintColor`](docs/imagestyleproptypes.html#tintcolor) -- [`overlayColor`](docs/imagestyleproptypes.html#overlaycolor) +[Image](docs/image.html) style props. +### Props +- [Layout Props...](docs/layout-props.html#props) +- [Shadow Props...](docs/shadow-props.html#props) +- [Transforms...](docs/transforms.html#props) +- [`borderTopRightRadius`](docs/image-style-props.html#bordertoprightradius) +- [`backfaceVisibility`](docs/image-style-props.html#backfacevisibility) +- [`borderBottomLeftRadius`](docs/image-style-props.html#borderbottomleftradius) +- [`borderBottomRightRadius`](docs/image-style-props.html#borderbottomrightradius) +- [`borderColor`](docs/image-style-props.html#bordercolor) +- [`borderRadius`](docs/image-style-props.html#borderradius) +- [`borderTopLeftRadius`](docs/image-style-props.html#bordertopleftradius) +- [`backgroundColor`](docs/image-style-props.html#backgroundcolor) +- [`borderWidth`](docs/image-style-props.html#borderwidth) +- [`opacity`](docs/image-style-props.html#opacity) +- [`overflow`](docs/image-style-props.html#overflow) +- [`resizeMode`](docs/image-style-props.html#resizemode) +- [`tintColor`](docs/image-style-props.html#tintcolor) +- [`overlayColor`](docs/image-style-props.html#overlaycolor) diff --git a/docs/image.md b/docs/image.md index 804262a25622d0..d60304e4f03c98 100644 --- a/docs/image.md +++ b/docs/image.md @@ -109,7 +109,6 @@ Also, if you use GIF with ProGuard, you will need to add this rule in `proguard- ### Props -- [`style`](docs/image.html#style) - [`blurRadius`](docs/image.html#blurradius) - [`onLayout`](docs/image.html#onlayout) - [`onLoad`](docs/image.html#onload) @@ -126,6 +125,7 @@ Also, if you use GIF with ProGuard, you will need to add this rule in `proguard- - [`defaultSource`](docs/image.html#defaultsource) - [`onPartialLoad`](docs/image.html#onpartialload) - [`onProgress`](docs/image.html#onprogress) +- [`style`](docs/image.html#style) @@ -144,73 +144,6 @@ Also, if you use GIF with ProGuard, you will need to add this rule in `proguard- ## Props -### `style` - -> `ImageResizeMode` is an `Enum` for different image resizing modes, set via the -> `resizeMode` style property on `Image` components. The values are `contain`, `cover`, -> `stretch`, `center`, `repeat`. - -| Type | Required | -| - | - | -| style | No | - - - - [Layout Props...](docs/layout-props.html#props) - - - [Shadow Props...](docs/shadow-props.html#props) - - - [Transforms...](docs/transforms.html#props) - - - **`borderTopRightRadius`**: number - - - **`backfaceVisibility`**: enum('visible', 'hidden') - - - **`borderBottomLeftRadius`**: number - - - **`borderBottomRightRadius`**: number - - - **`borderColor`**: [color](docs/colors.html) - - - **`borderRadius`**: number - - - **`borderTopLeftRadius`**: number - - - **`backgroundColor`**: [color](docs/colors.html) - - - **`borderWidth`**: number - - - **`opacity`**: number - - - **`overflow`**: enum('visible', 'hidden') - - - **`resizeMode`**: Object.keys(ImageResizeMode) - - - **`tintColor`**: [color](docs/colors.html) - - Changes the color of all the non-transparent pixels to the tintColor. - - - **`overlayColor`**: string (_Android_) - - When the image has rounded corners, specifying an overlayColor will - cause the remaining space in the corners to be filled with a solid color. - This is useful in cases which are not supported by the Android - implementation of rounded corners: - - Certain resize modes, such as 'contain' - - Animated GIFs - - A typical way to use this prop is with images displayed on a solid - background and setting the `overlayColor` to the same color - as the background. - - For details of how this works under the hood, see - http://frescolib.org/docs/rounded-corners-and-circles.html - - - - - ---- - ### `blurRadius` blurRadius: the blur radius of the blur filter added to the image @@ -483,27 +416,25 @@ Invoked on download progress with `{nativeEvent: {loaded, total}}`. | function | No | iOS | +--- +### `style` - +| Type | Required | +| - | - | +| [style](docs/imagestyleproptypes.html) | No | ## Methods ### `getSize()` ```javascript -static getSize(uri: string, success: function, [failure]: function): +static getSize(uri: string, success: function, [failure]: function): void ``` -Retrieve the width and height (in pixels) of an image prior to displaying it. -This method can fail if the image cannot be found, or fails to download. +Retrieve the width and height (in pixels) of an image prior to displaying it. This method can fail if the image cannot be found, or fails to download. -In order to retrieve the image dimensions, the image may first need to be -loaded or downloaded, after which it will be cached. This means that in -principle you could use this method to preload images, however it is not -optimized for that purpose, and may in future be implemented in a way that -does not fully load/download the image data. A proper, supported way to -preload images will be provided as a separate API. +In order to retrieve the image dimensions, the image may first need to be loaded or downloaded, after which it will be cached. This means that in principle you could use this method to preload images, however it is not optimized for that purpose, and may in future be implemented in a way that does not fully load/download the image data. A proper, supported way to preload images will be provided as a separate API. Does not work for static image resources. @@ -511,9 +442,9 @@ Does not work for static image resources. | Name | Type | Required | Description | | - | - | - | - | -| uri | string | No | The location of the image. | -| success | function | No | The function that will be called if the image was successfully found and widthand height retrieved. | -| failure | function | Yes | The function that will be called if there was an error, such as failing toto retrieve the image. | +| uri | string | Yes | The location of the image. | +| success | function | Yes | The function that will be called if the image was successfully found and widthand height retrieved. | +| failure | function | No | The function that will be called if there was an error, such as failing toto retrieve the image. | @@ -523,7 +454,7 @@ Does not work for static image resources. ### `prefetch()` ```javascript -static prefetch(url: string): +Image.prefetch(url: string): ``` Prefetches a remote image for later use by downloading it to the disk @@ -533,7 +464,7 @@ cache | Name | Type | Required | Description | | - | - | - | - | -| url | string | No | The remote location of the image. | +| url | string | Yes | The remote location of the image. | diff --git a/docs/imageeditor.md b/docs/imageeditor.md index d0ec17a2fbe079..6495335866c3b8 100644 --- a/docs/imageeditor.md +++ b/docs/imageeditor.md @@ -26,19 +26,20 @@ previous: geolocation ### `cropImage()` ```javascript -static cropImage(uri, cropData, success, failure) +ImageEditor.cropImage(uri, cropData, success, failure) ``` +Crop the image specified by the URI param. If URI points to a remote image, it will be downloaded automatically. If the image cannot be loaded/downloaded, the failure callback will be called. -Crop the image specified by the URI param. If URI points to a remote -image, it will be downloaded automatically. If the image cannot be -loaded/downloaded, the failure callback will be called. - -If the cropping process is successful, the resultant cropped image -will be stored in the ImageStore, and the URI returned in the success -callback will point to the image in the store. Remember to delete the -cropped image from the ImageStore when you are done with it. - +If the cropping process is successful, the resultant cropped image will be stored in the ImageStore, and the URI returned in the success callback will point to the image in the store. Remember to delete the cropped image from the ImageStore when you are done with it. +**Crop Data Options:** +The following options can be used with the `cropData` parameter: +| Name | Type | Required | Description | +| - | - | - | - | +| offset | `{ x: number, y: number}` | Yes | The top-left corner of the cropped image, specified in the original image's coordinate space. | +| size | `{ width: number, height: number }` | Yes | The size (dimensions) of the cropped image, specified in the original image's coordinate space. | +| displaySize | `{ width: number, height: number }` | No | Size to scale the cropped image to. | +| resizeMode | `enum( contain: string, cover: string, stretch: string }` | No | The resizing mode to use when scaling the image. If the `displaySize` param is not specified, this has no effect. | diff --git a/docs/imagepickerios.md b/docs/imagepickerios.md index 238f2437239a7e..52670059309f6b 100644 --- a/docs/imagepickerios.md +++ b/docs/imagepickerios.md @@ -29,7 +29,7 @@ previous: imageeditor ### `canRecordVideos()` ```javascript -static canRecordVideos(callback) +ImagePickerIOS.canRecordVideos(callback) ``` @@ -39,7 +39,7 @@ static canRecordVideos(callback) ### `canUseCamera()` ```javascript -static canUseCamera(callback) +ImagePickerIOS.canUseCamera(callback) ``` @@ -49,7 +49,7 @@ static canUseCamera(callback) ### `openCameraDialog()` ```javascript -static openCameraDialog(config, successCallback, cancelCallback) +ImagePickerIOS.openCameraDialog(config, successCallback, cancelCallback) ``` @@ -59,7 +59,7 @@ static openCameraDialog(config, successCallback, cancelCallback) ### `openSelectDialog()` ```javascript -static openSelectDialog(config, successCallback, cancelCallback) +ImagePickerIOS.openSelectDialog(config, successCallback, cancelCallback) ``` diff --git a/docs/imagestore.md b/docs/imagestore.md index 910ec25907fd42..a0210206c9a09e 100644 --- a/docs/imagestore.md +++ b/docs/imagestore.md @@ -29,7 +29,7 @@ previous: imagepickerios ### `hasImageForTag()` ```javascript -static hasImageForTag(uri, callback) +ImageStore.hasImageForTag(uri, callback) ``` @@ -44,7 +44,7 @@ Check if the ImageStore contains image data for the specified URI. ### `removeImageForTag()` ```javascript -static removeImageForTag(uri) +ImageStore.removeImageForTag(uri) ``` @@ -63,7 +63,7 @@ will simply fail silently. ### `addImageFromBase64()` ```javascript -static addImageFromBase64(base64ImageData, success, failure) +ImageStore.addImageFromBase64(base64ImageData, success, failure) ``` @@ -85,7 +85,7 @@ than necessary. ### `getBase64ForTag()` ```javascript -static getBase64ForTag(uri, success, failure) +ImageStore.getBase64ForTag(uri, success, failure) ``` diff --git a/docs/interactionmanager.md b/docs/interactionmanager.md index cb034edc4e9372..2c19e6449ffb1b 100644 --- a/docs/interactionmanager.md +++ b/docs/interactionmanager.md @@ -82,7 +82,7 @@ from executing, making apps more responsive. ### `runAfterInteractions()` ```javascript -static runAfterInteractions(task) +InteractionManager.runAfterInteractions(task) ``` @@ -97,7 +97,7 @@ Schedule a function to run after all interactions have completed. Returns a canc ### `createInteractionHandle()` ```javascript -static createInteractionHandle() +InteractionManager.createInteractionHandle() ``` @@ -111,7 +111,7 @@ Notify manager that an interaction has started. ### `clearInteractionHandle()` ```javascript -static clearInteractionHandle(handle) +InteractionManager.clearInteractionHandle(handle) ``` @@ -125,7 +125,7 @@ Notify manager that an interaction has completed. ### `setDeadline()` ```javascript -static setDeadline(deadline) +InteractionManager.setDeadline(deadline) ``` diff --git a/docs/keyboard.md b/docs/keyboard.md index 374a7e588d167e..418611d31f6dc6 100644 --- a/docs/keyboard.md +++ b/docs/keyboard.md @@ -68,7 +68,7 @@ class Example extends Component { ### `addListener()` ```javascript -static addListener(eventName, callback) +Keyboard.addListener(eventName, callback) ``` @@ -102,7 +102,7 @@ since there is no native corresponding event. ### `removeListener()` ```javascript -static removeListener(eventName, callback) +Keyboard.removeListener(eventName, callback) ``` @@ -119,7 +119,7 @@ Removes a specific listener. ### `removeAllListeners()` ```javascript -static removeAllListeners(eventName) +Keyboard.removeAllListeners(eventName) ``` @@ -135,7 +135,7 @@ Removes all listeners for a specific event type. ### `dismiss()` ```javascript -static dismiss() +Keyboard.dismiss() ``` diff --git a/docs/keyboardavoidingview.md b/docs/keyboardavoidingview.md index b13b3ff9c7f2a6..b5e0fdff23aa7a 100644 --- a/docs/keyboardavoidingview.md +++ b/docs/keyboardavoidingview.md @@ -12,7 +12,7 @@ It can automatically adjust either its position or bottom padding based on the p ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [ViewPropTypes props...](docs/viewproptypes.html#props) - [`keyboardVerticalOffset`](docs/keyboardavoidingview.html#keyboardverticaloffset) - [`behavior`](docs/keyboardavoidingview.html#behavior) - [`contentContainerStyle`](docs/keyboardavoidingview.html#contentcontainerstyle) @@ -68,7 +68,7 @@ The style of the content container(View) when behavior is 'position'. | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | diff --git a/docs/layout-props.md b/docs/layout-props.md index 6e5e919c523c62..90d4d39c92443b 100644 --- a/docs/layout-props.md +++ b/docs/layout-props.md @@ -4,7 +4,7 @@ title: Layout Props layout: docs category: APIs permalink: docs/layout-props.html -next: shadow-props +next: picker-style-props previous: vibrationios --- ### Props diff --git a/docs/layoutanimation.md b/docs/layoutanimation.md index 5e4255938d3da6..31a92f2c6b9244 100644 --- a/docs/layoutanimation.md +++ b/docs/layoutanimation.md @@ -46,7 +46,7 @@ Note that in order to get this to work on **Android** you need to set the follow ### `configureNext()` ```javascript -static configureNext(config, onAnimationDidEnd?) +LayoutAnimation.configureNext(config, onAnimationDidEnd?) ``` @@ -71,7 +71,7 @@ Only supported on iOS. ### `create()` ```javascript -static create(duration, type, creationProp) +LayoutAnimation.create(duration, type, creationProp) ``` @@ -85,7 +85,7 @@ Helper for creating a config for `configureNext`. ### `checkConfig()` ```javascript -static checkConfig(config, location, name) +LayoutAnimation.checkConfig(config, location, name) ``` diff --git a/docs/linking.md b/docs/linking.md index 6eed2276e6e8ae..a3194bfb2dd3aa 100644 --- a/docs/linking.md +++ b/docs/linking.md @@ -206,10 +206,9 @@ The method returns a `Promise` object. If the user confirms the open dialog or t url automatically opens, the promise is resolved. If the user cancels the open dialog or there are no registered applications for the url, the promise is rejected. -NOTE: This method will fail if the system doesn't know how to open the specified URL. -If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first. +> This method will fail if the system doesn't know how to open the specified URL. If you're passing in a non-http(s) URL, it's best to check {@code canOpenURL} first. -NOTE: For web URLs, the protocol ("http://", "https://") must be set accordingly! +> For web URLs, the protocol ("http://", "https://") must be set accordingly! @@ -225,13 +224,16 @@ canOpenURL(url) Determine whether or not an installed app can handle a given URL. -NOTE: For web URLs, the protocol ("http://", "https://") must be set accordingly! +> For web URLs, the protocol ("http://", "https://") must be set accordingly! -NOTE: As of iOS 9, your app needs to provide the `LSApplicationQueriesSchemes` key +> As of iOS 9, your app needs to provide the `LSApplicationQueriesSchemes` key inside `Info.plist` or canOpenURL will always return false. -@param URL the URL to open +**Parameters:** +| Name | Type | Required | Description | +| - | - | - | - | +| url | string | Yes | The URL to open | @@ -247,7 +249,7 @@ getInitialURL() If the app launch was triggered by an app link, it will give the link url, otherwise it will give `null` -NOTE: To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents +> To support deep linking on Android, refer http://developer.android.com/training/app-indexing/deep-linking.html#handling-intents diff --git a/docs/maskedviewios.md b/docs/maskedviewios.md index 91ca93b1e331f1..0de578a532ef64 100644 --- a/docs/maskedviewios.md +++ b/docs/maskedviewios.md @@ -43,7 +43,7 @@ transparent pixels block that content. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`maskElement`](docs/maskedviewios.html#maskelement) @@ -59,7 +59,7 @@ transparent pixels block that content. ### `maskElement` - +Should be a React element to be rendered and applied as the mask for the child element. | Type | Required | | - | - | diff --git a/docs/modal.md b/docs/modal.md index ac2255d9b32aa7..673fb545932f04 100644 --- a/docs/modal.md +++ b/docs/modal.md @@ -67,7 +67,7 @@ The `onRequestClose` callback is called when the user taps the hardware back but | Type | Required | | - | - | -| (Platform.isTVOS || Platform.OS === 'android') ? PropTypes.func.isRequired : PropTypes.func | No | +| function | Required on Android and Apple TV | diff --git a/docs/navigatorios.md b/docs/navigatorios.md index 342902885fdd7a..893e2ad32b42b5 100644 --- a/docs/navigatorios.md +++ b/docs/navigatorios.md @@ -7,21 +7,11 @@ permalink: docs/navigatorios.html next: picker previous: modal --- -`NavigatorIOS` is a wrapper around -[`UINavigationController`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/), -enabling you to implement a navigation stack. It works exactly the same as it -would on a native app using `UINavigationController`, providing the same -animations and behavior from UIKit. - -As the name implies, it is only available on iOS. Take a look at -[`React Navigation`](https://reactnavigation.org/) for a cross-platform -solution in JavaScript, or check out either of these components for native -solutions: [native-navigation](http://airbnb.io/native-navigation/), -[react-native-navigation](https://github.com/wix/react-native-navigation). - -To set up the navigator, provide the `initialRoute` prop with a route -object. A route object is used to describe each scene that your app -navigates to. `initialRoute` represents the first route in your navigator. +`NavigatorIOS` is a wrapper around [`UINavigationController`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/), enabling you to implement a navigation stack. It works exactly the same as it would on a native app using `UINavigationController`, providing the same animations and behavior from UIKit. + +As the name implies, it is only available on iOS. Take a look at [`React Navigation`](https://reactnavigation.org/) for a cross-platform solution in JavaScript, or check out either of these components for native solutions: [native-navigation](http://airbnb.io/native-navigation/), [react-native-navigation](https://github.com/wix/react-native-navigation). + +To set up the navigator, provide the `initialRoute` prop with a route object. A route object is used to describe each scene that your app navigates to. `initialRoute` represents the first route in your navigator. ``` import PropTypes from 'prop-types'; @@ -67,13 +57,9 @@ class MyScene extends Component { } ``` -In this code, the navigator renders the component specified in initialRoute, -which in this case is `MyScene`. This component will receive a `route` prop -and a `navigator` prop representing the navigator. The navigator's navigation -bar will render the title for the current scene, "My Initial Scene". +In this code, the navigator renders the component specified in initialRoute, which in this case is `MyScene`. This component will receive a `route` prop and a `navigator` prop representing the navigator. The navigator's navigation bar will render the title for the current scene, "My Initial Scene". -You can optionally pass in a `passProps` property to your `initialRoute`. -`NavigatorIOS` passes this in as props to the rendered component: +You can optionally pass in a `passProps` property to your `initialRoute`. `NavigatorIOS` passes this in as props to the rendered component: ``` initialRoute={{ @@ -87,10 +73,7 @@ You can then access the props passed in via `{this.props.myProp}`. #### Handling Navigation -To trigger navigation functionality such as pushing or popping a view, you -have access to a `navigator` object. The object is passed in as a prop to any -component that is rendered by `NavigatorIOS`. You can then call the -relevant methods to perform the navigation action you need: +To trigger navigation functionality such as pushing or popping a view, you have access to a `navigator` object. The object is passed in as a prop to any component that is rendered by `NavigatorIOS`. You can then call the relevant methods to perform the navigation action you need: ``` class MyView extends Component { @@ -119,8 +102,7 @@ class MyView extends Component { } ``` -You can also trigger navigator functionality from the `NavigatorIOS` -component: +You can also trigger navigator functionality from the `NavigatorIOS` component: ``` class NavvyIOS extends Component { @@ -150,18 +132,11 @@ class NavvyIOS extends Component { } ``` -The code above adds a `_handleNavigationRequest` private method that is -invoked from the `NavigatorIOS` component when the right navigation bar item -is pressed. To get access to the navigator functionality, a reference to it -is saved in the `ref` prop and later referenced to push a new scene into the -navigation stack. +The code above adds a `_handleNavigationRequest` private method that is invoked from the `NavigatorIOS` component when the right navigation bar item is pressed. To get access to the navigator functionality, a reference to it is saved in the `ref` prop and later referenced to push a new scene into the navigation stack. #### Navigation Bar Configuration -Props passed to `NavigatorIOS` will set the default configuration -for the navigation bar. Props passed as properties to a route object will set -the configuration for that route's navigation bar, overriding any props -passed to the `NavigatorIOS` component. +Props passed to `NavigatorIOS` will set the default configuration for the navigation bar. Props passed as properties to a route object will set the configuration for that route's navigation bar, overriding any props passed to the `NavigatorIOS` component. ``` _handleNavigationRequest() { @@ -183,8 +158,7 @@ render() { } ``` -In the example above the navigation bar color is changed when the new route -is pushed. +In the example above the navigation bar color is changed when the new route is pushed. ### Props @@ -228,14 +202,64 @@ is pushed. NavigatorIOS uses `route` objects to identify child views, their props, and navigation bar configuration. Navigation operations such as push -operations expect routes to look like this the `initialRoute`. +operations expect routes to look like this. | Type | Required | | - | - | -| object: {component: function,title: string,titleImage: Image.propTypes.source,passProps: object,backButtonIcon: Image.propTypes.source,backButtonTitle: string,leftButtonIcon: Image.propTypes.source,leftButtonTitle: string,leftButtonSystemIcon: Object.keys(SystemIcons),onLeftButtonPress: function,rightButtonIcon: Image.propTypes.source,rightButtonTitle: string,rightButtonSystemIcon: Object.keys(SystemIcons),onRightButtonPress: function,wrapperStyle: ViewPropTypes.style,navigationBarHidden: bool,shadowHidden: bool,tintColor: string,barTintColor: string,barStyle: enum('default', 'black'),titleTextColor: string,translucent: bool} | Yes | - - - +| object | Yes | + +**Routes:** + +The following parameters can be used to define a route: + +* `**component**`: function + The React Class to render for this route. +* `**title**`: string + The title displayed in the navigation bar and the back button for this route. +* `**titleImage**`: [Image](docs/image.html) + If set, a title image will appear instead of the text title. +* `**passProps**`: object + Use this to specify additional props to pass to the rendered component. `NavigatorIOS` will automatically pass in `route` and `navigator` props to the comoponent. +* `**backButtonIcon**`: [Image](docs/image.html) + If set, the left navigation button image will be displayed using this source. Note that this doesn't apply to the header of the current view, but to those views that are subsequently pushed. +* `**backButtonTitle**`: string + If set, the left navigation button text will be set to this. Note that this doesn't apply to the left button of the current view, but to those views that are subsequently pushed. +* `**leftButtonIcon**`: [Image](docs/image.html) + If set, the left navigation button image will be displayed using this source. +* `**leftButtonTitle**`: string + If set, the left navigation button will display this text. +* `**leftButtonSystemIcon**`: [SystemIcon](docs/navigatorios.html#system-icons) + If set, the left header button will appear with this system icon. See below for supported icons. +* `**onLeftButtonPress**`: function + This function will be invoked when the left navigation bar item is pressed. +* `**rightButtonIcon**`: [Image](docs/image.html) + If set, the right navigation button image will be displayed using this source. +* `**rightButtonTitle**`: string + If set, the right navigation button will display this text. +* `**rightButtonSystemIcon**`: [SystemIcon](docs/navigatorios.html#system-icons) + If set, the right header button will appear with this system icon. See below for supported icons. +* `**onRightButtonPress**`: function + This function will be invoked when the right navigation bar item is pressed. +* `**wrapperStyle**`: [ViewPropTypes.style](docs/viewproptypes.html#style) + Styles for the navigation item containing the component. +* `**navigationBarHidden**`: boolean + Boolean value that indicates whether the navigation bar is hidden. +* `**shadowHidden**`: boolean + Boolean value that indicates whether to hide the 1px hairline shadow. +* `**tintColor**`: string + The color used for the buttons in the navigation bar. +* `**barTintColor**`: string + The background color of the navigation bar. +* `**barStyle**`: enum('default', 'black') + The style of the navigation bar. Supported values are 'default', 'black'. Use 'black' instead of setting `barTintColor` to black. This produces a navigation bar with the native iOS style with higher translucency. +* `**titleTextColor**`: string + The text color of the navigation bar title. +* `**translucent**`: boolean + Boolean value that indicates whether the navigation bar is translucent. + +#### System Icons + +Used in `leftButtonSystemIcon` and `rightButtonSystemIcon`. Supported icons are `done`, `cancel`, `edit`, `save`, `add`, `compose`, `reply`, `action`, `organize`, `bookmarks`, `search`, `refresh`, `stop`, `camera`, `trash`, `play`, `pause`, `rewind`, `fast-forward`, `undo`, `redo`, and `page-curl`. --- @@ -295,7 +319,7 @@ A common use case is to set the `backgroundColor` for every scene. | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | @@ -384,7 +408,7 @@ Navigate forward to a new route. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route to navigate to. | +| route | object | Yes | The new route to navigate to. | @@ -403,7 +427,7 @@ Go back N scenes at once. When N=1, behavior matches `pop()`. | Name | Type | Required | Description | | - | - | - | - | -| n | number | No | The number of scenes to pop. | +| n | number | Yes | The number of scenes to pop. | @@ -434,8 +458,8 @@ Replace a route in the navigation stack. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route that will replace the specified one. | -| index | number | No | The route into the stack that should be replaced. If it is negative, it counts from the back of the stack. | +| route | object | Yes | The new route that will replace the specified one. | +| index | number | Yes | The route into the stack that should be replaced. If it is negative, it counts from the back of the stack. | @@ -455,7 +479,7 @@ load the view for the new route. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route to navigate to. | +| route | object | Yes | The new route to navigate to. | @@ -474,7 +498,7 @@ Replace the route/view for the previous scene. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route to will replace the previous scene. | +| route | object | Yes | The new route to will replace the previous scene. | @@ -505,7 +529,7 @@ Go back to the item for a particular route object. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route to navigate to. | +| route | object | Yes | The new route to navigate to. | @@ -524,7 +548,7 @@ Replaces the previous route/view and transitions back to it. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route that replaces the previous scene. | +| route | object | Yes | The new route that replaces the previous scene. | @@ -543,7 +567,7 @@ Replaces the top item and pop to it. | Name | Type | Required | Description | | - | - | - | - | -| route | object | No | The new route that will replace the topmost item. | +| route | object | Yes | The new route that will replace the topmost item. | diff --git a/docs/netinfo.md b/docs/netinfo.md index 4f8cd6c6d111a8..2d7eb73e44c029 100644 --- a/docs/netinfo.md +++ b/docs/netinfo.md @@ -8,7 +8,7 @@ next: panresponder previous: linking --- -NetInfo exposes info about online/offline status +NetInfo exposes info about online/offline status. ``` NetInfo.getConnectionInfo().then((connectionInfo) => { @@ -57,44 +57,6 @@ app's `AndroidManifest.xml`: `` -### isConnectionExpensive - -Available on Android. Detect if the current active connection is metered or not. A network is -classified as metered when the user is sensitive to heavy data usage on that connection due to -monetary costs, data limitations or battery/performance issues. - -``` -NetInfo.isConnectionExpensive() -.then(isConnectionExpensive => { - console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive')); -}) -.catch(error => { - console.error(error); -}); -``` - -### isConnected - -Available on all platforms. Asynchronously fetch a boolean to determine -internet connectivity. - -``` -NetInfo.isConnected.fetch().then(isConnected => { - console.log('First, is ' + (isConnected ? 'online' : 'offline')); -}); -function handleFirstConnectivityChange(isConnected) { - console.log('Then, is ' + (isConnected ? 'online' : 'offline')); - NetInfo.isConnected.removeEventListener( - 'connectionChange', - handleFirstConnectivityChange - ); -} -NetInfo.isConnected.addEventListener( - 'connectionChange', - handleFirstConnectivityChange -); -``` - ### Connectivity Types (deprecated) The following connectivity types are deprecated. They're used by the deprecated APIs `fetch` and the `change` event. @@ -148,7 +110,7 @@ The rest of the connectivity types are hidden by the Android API, but can be use ### `addEventListener()` ```javascript -static addEventListener(eventName, handler) +NetInfo.addEventListener(eventName, handler) ``` @@ -170,7 +132,7 @@ Adds an event handler. Supported events: ### `removeEventListener()` ```javascript -static removeEventListener(eventName, handler) +NetInfo.removeEventListener(eventName, handler) ``` @@ -184,7 +146,7 @@ Removes the listener for network status changes. ### `fetch()` ```javascript -static fetch() +NetInfo.fetch() ``` @@ -199,7 +161,7 @@ resolves with one of the deprecated connectivity types listed above. ### `getConnectionInfo()` ```javascript -static getConnectionInfo() +NetInfo.getConnectionInfo() ``` @@ -215,12 +177,44 @@ respectively. ### `isConnectionExpensive()` ```javascript -static isConnectionExpensive() +NetInfo.isConnectionExpensive() +``` + +Available on Android. Detect if the current active connection is metered or not. A network is +classified as metered when the user is sensitive to heavy data usage on that connection due to +monetary costs, data limitations or battery/performance issues. + +``` +NetInfo.isConnectionExpensive() +.then(isConnectionExpensive => { + console.log('Connection is ' + (isConnectionExpensive ? 'Expensive' : 'Not Expensive')); +}) +.catch(error => { + console.error(error); +}); ``` ## Properties +### `isConnected` +Available on all platforms. Asynchronously fetch a boolean to determine internet connectivity. +``` +NetInfo.isConnected.fetch().then(isConnected => { + console.log('First, is ' + (isConnected ? 'online' : 'offline')); +}); +function handleFirstConnectivityChange(isConnected) { + console.log('Then, is ' + (isConnected ? 'online' : 'offline')); + NetInfo.isConnected.removeEventListener( + 'connectionChange', + handleFirstConnectivityChange + ); +} +NetInfo.isConnected.addEventListener( + 'connectionChange', + handleFirstConnectivityChange +); +``` diff --git a/docs/panresponder.md b/docs/panresponder.md index 5bb6d7b71de810..35ed082b31c5fd 100644 --- a/docs/panresponder.md +++ b/docs/panresponder.md @@ -121,41 +121,31 @@ To see it in action, try the ### `create()` ```javascript -static create(config) +PanResponder.create(config) ``` - -@param {object} config Enhanced versions of all of the responder callbacks -that provide not only the typical `ResponderSyntheticEvent`, but also the -`PanResponder` gesture state. Simply replace the word `Responder` with -`PanResponder` in each of the typical `onResponder*` callbacks. For -example, the `config` object would look like: - - - `onMoveShouldSetPanResponder: (e, gestureState) => {...}` - - `onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}` - - `onStartShouldSetPanResponder: (e, gestureState) => {...}` - - `onStartShouldSetPanResponderCapture: (e, gestureState) => {...}` - - `onPanResponderReject: (e, gestureState) => {...}` - - `onPanResponderGrant: (e, gestureState) => {...}` - - `onPanResponderStart: (e, gestureState) => {...}` - - `onPanResponderEnd: (e, gestureState) => {...}` - - `onPanResponderRelease: (e, gestureState) => {...}` - - `onPanResponderMove: (e, gestureState) => {...}` - - `onPanResponderTerminate: (e, gestureState) => {...}` - - `onPanResponderTerminationRequest: (e, gestureState) => {...}` - - `onShouldBlockNativeResponder: (e, gestureState) => {...}` - - In general, for events that have capture equivalents, we update the - gestureState once in the capture phase and can use it in the bubble phase - as well. - - Be careful with onStartShould* callbacks. They only reflect updated - `gestureState` for start/end events that bubble/capture to the Node. - Once the node is the responder, you can rely on every start/end event - being processed by the gesture and `gestureState` being updated - accordingly. (numberActiveTouches) may not be totally accurate unless you - are the responder. - - +Enhanced versions of all of the responder callbacks +that provide not only the typical `ResponderSyntheticEvent`, but also the `PanResponder` gesture state. Simply replace the word `Responder` with +`PanResponder` in each of the typical `onResponder*` callbacks. + +For example, the `config` object would look like: + +- `onMoveShouldSetPanResponder: (e, gestureState) => {...}` +- `onMoveShouldSetPanResponderCapture: (e, gestureState) => {...}` +- `onStartShouldSetPanResponder: (e, gestureState) => {...}` +- `onStartShouldSetPanResponderCapture: (e, gestureState) => {...}` +- `onPanResponderReject: (e, gestureState) => {...}` +- `onPanResponderGrant: (e, gestureState) => {...}` +- `onPanResponderStart: (e, gestureState) => {...}` +- `onPanResponderEnd: (e, gestureState) => {...}` +- `onPanResponderRelease: (e, gestureState) => {...}` +- `onPanResponderMove: (e, gestureState) => {...}` +- `onPanResponderTerminate: (e, gestureState) => {...}` +- `onPanResponderTerminationRequest: (e, gestureState) => {...}` +- `onShouldBlockNativeResponder: (e, gestureState) => {...}` + +In general, for events that have capture equivalents, we update the gestureState once in the capture phase and can use it in the bubble phase as well. + +Be careful with onStartShould* callbacks. They only reflect updated `gestureState` for start/end events that bubble/capture to the Node. Once the node is the responder, you can rely on every start/end event being processed by the gesture and `gestureState` being updated accordingly. (numberActiveTouches) may not be totally accurate unless you are the responder. diff --git a/docs/permissionsandroid.md b/docs/permissionsandroid.md index e136da5a555019..e56db936decfa1 100644 --- a/docs/permissionsandroid.md +++ b/docs/permissionsandroid.md @@ -19,23 +19,16 @@ previous: panresponder

-`PermissionsAndroid` provides access to Android M's new permissions model. -Some permissions are granted by default when the application is installed -so long as they appear in `AndroidManifest.xml`. However, "dangerous" -permissions require a dialog prompt. You should use this module for those +`PermissionsAndroid` provides access to Android M's new permissions model. Some permissions are granted by default when the application is installed so long as they appear in `AndroidManifest.xml`. However, "dangerous" permissions require a dialog prompt. You should use this module for those permissions. -On devices before SDK version 23, the permissions are automatically granted -if they appear in the manifest, so `check` and `request` -should always be true. +On devices before SDK version 23, the permissions are automatically granted if they appear in the manifest, so `check` and `request` should always be true. -If a user has previously turned off a permission that you prompt for, the OS -will advise your app to show a rationale for needing the permission. The -optional `rationale` argument will show a dialog prompt only if -necessary - otherwise the normal permission prompt will appear. +If a user has previously turned off a permission that you prompt for, the OS will advise your app to show a rationale for needing the permission. The optional `rationale` argument will show a dialog prompt only if necessary - otherwise the normal permission prompt will appear. ### Example -``` + +```javascript import { PermissionsAndroid } from 'react-native'; async function requestCameraPermission() { @@ -63,11 +56,11 @@ async function requestCameraPermission() { ### Methods - [`constructor`](docs/permissionsandroid.html#constructor) -- [`checkPermission`](docs/permissionsandroid.html#checkpermission) - [`check`](docs/permissionsandroid.html#check) -- [`requestPermission`](docs/permissionsandroid.html#requestpermission) - [`request`](docs/permissionsandroid.html#request) - [`requestMultiple`](docs/permissionsandroid.html#requestmultiple) +- [`requestPermission`](docs/permissionsandroid.html#requestpermission) +- [`checkPermission`](docs/permissionsandroid.html#checkpermission) @@ -88,97 +81,71 @@ constructor() --- -### `checkPermission()` +### `check()` ```javascript -checkPermission(permission) +check(permission) ``` -DEPRECATED - use check - -Returns a promise resolving to a boolean value as to whether the specified -permissions has been granted - -@deprecated - - +Returns a promise resolving to a boolean value as to whether the specified permissions has been granted --- -### `check()` +### `request()` ```javascript -check(permission) +request(permission, rationale?) ``` -Returns a promise resolving to a boolean value as to whether the specified -permissions has been granted +Prompts the user to enable a permission and returns a promise resolving to a string value indicating whether the user allowed or denied the request. + +If the optional rationale argument is included (which is an object with a `title` and `message`), this function checks with the OS whether it is necessary to show a dialog [explaining why the permission is needed](https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog --- -### `requestPermission()` +### `requestMultiple()` ```javascript -requestPermission(permission, rationale?) +requestMultiple(permissions) ``` -DEPRECATED - use request - -Prompts the user to enable a permission and returns a promise resolving to a -boolean value indicating whether the user allowed or denied the request - -If the optional rationale argument is included (which is an object with a -`title` and `message`), this function checks with the OS whether it is -necessary to show a dialog explaining why the permission is needed -(https://developer.android.com/training/permissions/requesting.html#explain) -and then shows the system permission dialog - -@deprecated - - +Prompts the user to enable multiple permissions in the same dialog and returns an object with the permissions as keys and strings as values indicating whether the user allowed or denied the request --- -### `request()` +### `checkPermission()` ```javascript -request(permission, rationale?) +checkPermission(permission) ``` -Prompts the user to enable a permission and returns a promise resolving to a -string value indicating whether the user allowed or denied the request - -If the optional rationale argument is included (which is an object with a -`title` and `message`), this function checks with the OS whether it is -necessary to show a dialog explaining why the permission is needed -(https://developer.android.com/training/permissions/requesting.html#explain) -and then shows the system permission dialog +**DEPRECATED** - use [check](docs/permissionsandroid.html#check) +Returns a promise resolving to a boolean value as to whether the specified permissions has been granted --- -### `requestMultiple()` +### `requestPermission()` ```javascript -requestMultiple(permissions) +requestPermission(permission, rationale?) ``` -Prompts the user to enable multiple permissions in the same dialog and -returns an object with the permissions as keys and strings as values -indicating whether the user allowed or denied the request - +**DEPRECATED** - use [request](docs/permissionsandroid.html#request) +Prompts the user to enable a permission and returns a promise resolving to a boolean value indicating whether the user allowed or denied the request. +If the optional rationale argument is included (which is an object with a `title` and `message`), this function checks with the OS whether it is necessary to show a dialog [explaining why the permission is needed](https://developer.android.com/training/permissions/requesting.html#explain) and then shows the system permission dialog diff --git a/docs/picker-item.md b/docs/picker-item.md new file mode 100644 index 00000000000000..6e1481d153c9ae --- /dev/null +++ b/docs/picker-item.md @@ -0,0 +1,57 @@ +--- +id: picker-item +title: Picker.Item +layout: docs +category: components +permalink: docs/picker-item.html +next: pickerios +previous: picker +--- + +Individual selectable item in a [Picker](docs/picker.html). + +### Props + +- [`label`](docs/picker-item.html#label) +- [`color`](docs/picker-item.html#color) +- [`testID`](docs/picker-item.html#testid) +- [`value`](docs/picker-item.html#value) + +--- + +# Reference + +## Props + +### `label` + +Text to display for this item. + +| Type | Required | +| - | - | +| string | Yes | + +### `color` + +The value to be passed to picker's `onValueChange` callback when this item is selected. Can be a string or an integer. + +| Type | Required | +| - | - | +| [color](docs/colors.html) | No | + +### `testID` + +Used to locate the item in end-to-end tests. + +| Type | Required | +| - | - | +| string | No | + +### `value` + +Color of this item's text. + +| Type | Required | Platform | +| - | - | - | +| any | No | Android | + diff --git a/docs/picker-style-props.md b/docs/picker-style-props.md new file mode 100644 index 00000000000000..b9df932a5ba5d0 --- /dev/null +++ b/docs/picker-style-props.md @@ -0,0 +1,32 @@ +--- +id: picker-style-props +title: Picker Style Props +layout: docs +category: APIs +permalink: docs/picker-style-props.html +next: shadow-props +previous: layout-props +--- + +[Picker](docs/picker.html) style props. + +### Props + +- [View Style Props...](docs/view-style-props.html) +- [`color`](docs/picker-style-props.html#color) + + + +--- + +# Reference + +## Props + +### `color` + + + +| Type | Required | +| - | - | +| [color](docs/color.html) | No | diff --git a/docs/picker.md b/docs/picker.md index 94918d361edb3e..3ce067f96643c3 100644 --- a/docs/picker.md +++ b/docs/picker.md @@ -4,9 +4,10 @@ title: Picker layout: docs category: components permalink: docs/picker.html -next: pickerios +next: picker-item previous: navigatorios --- + Renders the native picker component on iOS and Android. Example: Display > Font size, on iOS it will always return the default pixel ratio. -@platform android - +Currently this is only implemented on Android and reflects the user preference set in Settings > Display > Font size, on iOS it will always return the default pixel ratio. +| Platform | +| - | +| Android | --- @@ -123,10 +122,9 @@ Settings > Display > Font size, on iOS it will always return the default pixel r ### `getPixelSizeForLayoutSize()` ```javascript -static getPixelSizeForLayoutSize(layoutSize) +PixelRatio.getPixelSizeForLayoutSize(layoutSize) ``` - Converts a layout size (dp) to pixel size (px). Guaranteed to return an integer number. @@ -139,27 +137,9 @@ Guaranteed to return an integer number. ### `roundToNearestPixel()` ```javascript -static roundToNearestPixel(layoutSize) -``` - - -Rounds a layout size (dp) to the nearest layout size that corresponds to -an integer number of pixels. For example, on a device with a PixelRatio -of 3, `PixelRatio.roundToNearestPixel(8.4) = 8.33`, which corresponds to -exactly (8.33 * 3) = 25 pixels. - - - - ---- - -### `startDetecting()` - -```javascript -static startDetecting() +PixelRatio.roundToNearestPixel(layoutSize) ``` -// No-op for iOS, but used on the web. Should not be documented. - +Rounds a layout size (dp) to the nearest layout size that corresponds to an integer number of pixels. For example, on a device with a PixelRatio of 3, `PixelRatio.roundToNearestPixel(8.4) = 8.33`, which corresponds to exactly (8.33 * 3) = 25 pixels. diff --git a/docs/progressbarandroid.md b/docs/progressbarandroid.md index ba0232410c0df3..b316ea1224130a 100644 --- a/docs/progressbarandroid.md +++ b/docs/progressbarandroid.md @@ -31,7 +31,7 @@ render: function() { ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`animating`](docs/progressbarandroid.html#animating) - [`color`](docs/progressbarandroid.html#color) - [`indeterminate`](docs/progressbarandroid.html#indeterminate) @@ -107,13 +107,13 @@ The progress value (between 0 and 1). Style of the ProgressBar. One of: -- Horizontal -- Normal (default) -- Small -- Large -- Inverse -- SmallInverse -- LargeInverse +- `Horizontal` +- `Normal` (default) +- `Small` +- `Large` +- `Inverse` +- `SmallInverse` +- `LargeInverse` | Type | Required | | - | - | diff --git a/docs/progressviewios.md b/docs/progressviewios.md index bc8cd300b2f25f..b9c9bdedb27ece 100644 --- a/docs/progressviewios.md +++ b/docs/progressviewios.md @@ -11,7 +11,7 @@ Use `ProgressViewIOS` to render a UIProgressView on iOS. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`progress`](docs/progressviewios.html#progress) - [`progressImage`](docs/progressviewios.html#progressimage) - [`progressTintColor`](docs/progressviewios.html#progresstintcolor) diff --git a/docs/pushnotificationios.md b/docs/pushnotificationios.md index b452ffdcdb4e23..1093e3da9d5e69 100644 --- a/docs/pushnotificationios.md +++ b/docs/pushnotificationios.md @@ -70,7 +70,7 @@ And then in your AppDelegate implementation add the following: ### Methods -- [`=`](docs/pushnotificationios.html#) +- [`presentLocalNotification`](docs/pushnotificationios.html#presentlocalnotification) - [`scheduleLocalNotification`](docs/pushnotificationios.html#schedulelocalnotification) - [`cancelAllLocalNotifications`](docs/pushnotificationios.html#cancelalllocalnotifications) - [`removeAllDeliveredNotifications`](docs/pushnotificationios.html#removealldeliverednotifications) @@ -96,8 +96,9 @@ And then in your AppDelegate implementation add the following: - [`getBadgeCount`](docs/pushnotificationios.html#getbadgecount) - [`getData`](docs/pushnotificationios.html#getdata) +## Events - +- [PushNotificationEventName](docs/pushnotificationios.html#pushnotificationeventname) --- @@ -105,12 +106,23 @@ And then in your AppDelegate implementation add the following: ## Methods -### `=()` +### `presentLocalNotification()` ```javascript -=(NewData, NoData, ResultFailed, }, static, (, :) +presentLocalNotification(details) ``` +Schedules the localNotification for immediate presentation. + +`details` is an object containing: + +- `alertBody` : The message displayed in the notification alert. +- `alertAction` : The "action" displayed beneath an actionable notification. Defaults to "view"; +- `soundName` : The sound played when the notification is fired (optional). +- `isSilent` : If true, the notification will appear without sound (optional). +- `category` : The category of this notification, required for actionable notifications (optional). +- `userInfo` : An optional object containing additional notification data. +- `applicationIconBadgeNumber` (optional) : The number to display as the app's icon badge. The default value of this property is 0, which means that no badge is displayed. --- @@ -177,18 +189,22 @@ static getDeliveredNotifications(callback) ``` -Provides you with a list of the app’s notifications that are still displayed in Notification Center +Provides you with a list of the app’s notifications that are still displayed in Notification Center. -@param callback Function which receive an array of delivered notifications +A delivered notification is an object containing: - A delivered notification is an object containing: +- `identifier`: The identifier of this notification. +- `title`: The title of this notification. +- `body`: The body of this notification. +- `category`: The category of this notification, if has one. +- `userInfo`: An optional object containing additional notification data. +- `thread-id`: The thread identifier of this notification, if has one. -- `identifier` : The identifier of this notification. -- `title` : The title of this notification. -- `body` : The body of this notification. -- `category` : The category of this notification, if has one. -- `userInfo` : An optional object containing additional notification data. -- `thread-id` : The thread identifier of this notification, if has one. +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| callback | function | Yes | Function which receives an array of delivered notifications. | @@ -201,11 +217,13 @@ Provides you with a list of the app’s notifications that are still displayed i static removeDeliveredNotifications(identifiers) ``` +Removes the specified notifications from Notification Center. -Removes the specified notifications from Notification Center - -@param identifiers Array of notification identifiers +**Parameters:** +| Name | Type | Required | Description | +| - | - | - | - | +| identifiers | array | Yes | Array of notification identifiers | @@ -403,9 +421,7 @@ constructor(nativeNotif) ``` -You will never need to instantiate `PushNotificationIOS` yourself. -Listening to the `notification` event and invoking -`getInitialNotification` is sufficient +You will never need to instantiate `PushNotificationIOS` yourself. Listening to the `notification` event and invoking `getInitialNotification` is sufficient. @@ -419,19 +435,11 @@ finish(fetchResult) ``` -This method is available for remote notifications that have been received via: -`application:didReceiveRemoteNotification:fetchCompletionHandler:` -https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIApplicationDelegate_Protocol/#//apple_ref/occ/intfm/UIApplicationDelegate/application:didReceiveRemoteNotification:fetchCompletionHandler: - -Call this to execute when the remote notification handling is complete. When -calling this block, pass in the fetch result value that best describes -the results of your operation. You *must* call this handler and should do so -as soon as possible. For a list of possible values, see `PushNotificationIOS.FetchResult`. - -If you do not call this method your background remote notifications could -be throttled, to read more about it see the above documentation link. +This method is available for remote notifications that have been received via [`application:didReceiveRemoteNotification:fetchCompletionHandler:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application). +Call this to execute when the remote notification handling is complete. When calling this block, pass in the fetch result value that best describes the results of your operation. You *must* call this handler and should do so as soon as possible. For a list of possible values, see `PushNotificationIOS.FetchResult`. +If you do not call this method your background remote notifications could be throttled, to read more about it see the above documentation link. --- @@ -531,4 +539,13 @@ Gets the data object on the notif +## Events + +### `PushNotificationEventName` + +An event emitted by PushNotificationIOS. +- `notification` - Fired when a remote notification is received. The handler will be invoked with an instance of `PushNotificationIOS`. +- `localNotification` - Fired when a local notification is received. The handler will be invoked with an instance of `PushNotificationIOS`. +- `register` - Fired when the user registers for remote notifications. The handler will be invoked with a hex string representing the deviceToken. +- `registrationError` - Fired when the user fails to register for remote notifications. Typically occurs when APNS is having issues, or the device is a emulator. The handler will be invoked with `{message: string, code: number, details: any}`. \ No newline at end of file diff --git a/docs/refreshcontrol.md b/docs/refreshcontrol.md index d6ec9ce66827ec..6302f46297bb9e 100644 --- a/docs/refreshcontrol.md +++ b/docs/refreshcontrol.md @@ -53,7 +53,7 @@ in the `onRefresh` function otherwise the refresh indicator will stop immediatel ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`refreshing`](docs/refreshcontrol.html#refreshing) - [`onRefresh`](docs/refreshcontrol.html#onrefresh) - [`colors`](docs/refreshcontrol.html#colors) diff --git a/docs/scrollview.md b/docs/scrollview.md index 276582ca01f113..c73e45955333b0 100644 --- a/docs/scrollview.md +++ b/docs/scrollview.md @@ -43,7 +43,7 @@ supports out of the box. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`alwaysBounceVertical`](docs/scrollview.html#alwaysbouncevertical) - [`contentContainerStyle`](docs/scrollview.html#contentcontainerstyle) - [`keyboardDismissMode`](docs/scrollview.html#keyboarddismissmode) @@ -62,7 +62,6 @@ supports out of the box. - [`endFillColor`](docs/scrollview.html#endfillcolor) - [`overScrollMode`](docs/scrollview.html#overscrollmode) - [`scrollPerfTag`](docs/scrollview.html#scrollperftag) -- [`DEPRECATED_sendUpdatedChildFrames`](docs/scrollview.html#deprecated-sendupdatedchildframes) - [`alwaysBounceHorizontal`](docs/scrollview.html#alwaysbouncehorizontal) - [`horizontal`](docs/scrollview.html#horizontal) - [`automaticallyAdjustContentInsets`](docs/scrollview.html#automaticallyadjustcontentinsets) @@ -85,6 +84,7 @@ supports out of the box. - [`snapToAlignment`](docs/scrollview.html#snaptoalignment) - [`snapToInterval`](docs/scrollview.html#snaptointerval) - [`zoomScale`](docs/scrollview.html#zoomscale) +- [`DEPRECATED_sendUpdatedChildFrames`](docs/scrollview.html#deprecated-sendupdatedchildframes) @@ -141,7 +141,7 @@ const styles = StyleSheet.create({ | Type | Required | | - | - | -| StyleSheetPropType(ViewStylePropTypes) | No | +| [style](docs/view-style-props.html) | No | @@ -417,25 +417,6 @@ FpsListener for it to be useful. - ---- - -### `DEPRECATED_sendUpdatedChildFrames` - -When true, ScrollView will emit updateChildFrames data in scroll events, -otherwise will not compute or emit child frame data. This only exists -to support legacy issues, `onLayout` should be used instead to retrieve -frame data. -The default value is false. - - -| Type | Required | Platform | -| - | - | - | -| bool | No | iOS | - - - - --- ### `alwaysBounceHorizontal` @@ -796,6 +777,20 @@ The current scale of the scroll view content. The default value is 1.0. | number | No | iOS | +--- + +### `DEPRECATED_sendUpdatedChildFrames` + +**Deprecated.** When true, ScrollView will emit updateChildFrames data in scroll events, +otherwise will not compute or emit child frame data. This only exists +to support legacy issues, `onLayout` should be used instead to retrieve +frame data. +The default value is false. + + +| Type | Required | Platform | +| - | - | - | +| bool | No | iOS | diff --git a/docs/sectionlist.md b/docs/sectionlist.md index b6dced3898c348..d7bca81aa9ce96 100644 --- a/docs/sectionlist.md +++ b/docs/sectionlist.md @@ -7,6 +7,7 @@ permalink: docs/sectionlist.html next: segmentedcontrolios previous: scrollview --- + A performant interface for rendering sectioned lists, supporting the most handy features: - Fully cross-platform. @@ -25,46 +26,60 @@ If you don't need section support and want a simpler interface, use Simple Examples: - } - renderSectionHeader={({section}) =>
} - sections={[ // homogeneous rendering between sections - {data: [...], title: ...}, - {data: [...], title: ...}, - {data: [...], title: ...}, - ]} - /> - - - -This is a convenience wrapper around [``](docs/virtualizedlist.html), +```javascript + } + renderSectionHeader={({section}) =>
} + sections={[ // homogeneous rendering between sections + {data: [...], title: ...}, + {data: [...], title: ...}, + {data: [...], title: ...}, + ]} +/> + + +``` + +This is a convenience wrapper around [`VirtualizedList`](docs/virtualizedlist.html), and thus inherits its props (as well as those of `ScrollView`) that aren't explicitly listed here, along with the following caveats: -- Internal state is not preserved when content scrolls out of the render window. Make sure all - your data is captured in the item data or external stores like Flux, Redux, or Relay. -- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- - equal. Make sure that everything your `renderItem` function depends on is passed as a prop - (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on - changes. This includes the `data` prop and parent component state. -- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously - offscreen. This means it's possible to scroll faster than the fill rate and momentarily see - blank content. This is a tradeoff that can be adjusted to suit the needs of each application, - and we are working on improving it behind the scenes. -- By default, the list looks for a `key` prop on each item and uses that for the React key. - Alternatively, you can provide a custom `keyExtractor` prop. +- Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay. +- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- equal. Make sure that everything your `renderItem` function depends on is passed as a prop (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on changes. This includes the `data` prop and parent component state. +- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes. +- By default, the list looks for a `key` prop on each item and uses that for the React key. Alternatively, you can provide a custom `keyExtractor` prop. ### Props +- [`ScrollView` props...](docs/scrollview.html#props) +- [`VirtualizedList` props...](docs/virtualizedlist.html#props) +- [`sections`](docs/virtualizedlist.html#sections) +- [`renderItem`](docs/virtualizedlist.html#renderitem) +- [`ItemSeparatorComponent`](docs/virtualizedlist.html#itemseparatorcomponent) +- [`ItemSeparatorComponent`](docs/virtualizedlist.html#itemseparatorcomponent) +- [`ListEmptyComponent`](docs/virtualizedlist.html#listemptycomponent) +- [`ListFooterComponent`](docs/virtualizedlist.html#listgootercomponent) +SectionSeparatorComponent +- [`extradata`](docs/virtualizedlist.html#extradata) +- [`initialNumToRender`](docs/virtualizedlist.html#initialnumtorender) +- [`inverted`](docs/virtualizedlist.html#inverted) +- [`keyExtractor`](docs/virtualizedlist.html#keyextractor) +- [`onEndReached`](docs/virtualizedlist.html#onendreached) +- [`onEndReachedThreshold`](docs/virtualizedlist.html#onendreachedthreshold) +- [`onRefresh`](docs/virtualizedlist.html#onrefresh) +- [`onViewableItemsChanged`](docs/virtualizedlist.html#onviewableitemschanged) +- [`refreshing`](docs/virtualizedlist.html#refreshing) +- [`removeClippedSubviews`](docs/virtualizedlist.html#removeclippedsubviews) +- [`renderSectionHeader`](docs/virtualizedlist.html#removeclippedsubviews) +- [`renderSectionFooter`](docs/virtualizedlist.html#rendersectionfooter) - [`stickySectionHeadersEnabled`](docs/sectionlist.html#stickysectionheadersenabled) - - +- [`legacyImplementation`](docs/virtualizedlist.html#legacyimplementation) ### Methods @@ -88,9 +103,302 @@ here, along with the following caveats: ## Props -### `stickySectionHeadersEnabled` +### `sections` + +The actual data to render, akin to the `data` prop in [`FlatList`](/docs/flatlist.html#data). + +**General shape:** + +``` +sections: [{ + data: array, + [renderItem]: ({item: SectionItem, ...}) => element, + [ItemSeparatorComponent]: React Class Component | function | element, +}] +``` + +| Type | Required | +| - | - | +| array of objects | Yes | + + + +--- + + +### `renderItem` + +```javascript +renderItem({ item: object, index: number, section: object, separators: { highlight: function, unhighlight: function, updateProps: function(select: string, newProps: object) } }): [element] +``` + +Default renderer for every item in every section. Can be over-ridden on a per-section basis. + +Provides additional metadata like `index` if you need it, as well as a more generic `separators.updateProps` function which let's you set whatever props you want to change the rendering of either the leading separator or trailing separator in case the more common `highlight` and `unhighlight` (which set the `highlighted: boolean` prop) are insufficient for your use case. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `ItemSeparatorComponent` + +Rendered in between each item, but not at the top or bottom. By default, `highlighted`, `section`, and `[leading/trailing][Item/Separator]` props are provided. `renderItem` provides `separators.highlight`/`unhighlight` which will update the `highlighted` prop, but you can also add custom props with `separators.updateProps`. + +| Type | Required | +| - | - | +| component | No | + + + +--- + + +### `ListHeaderComponent` + +Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `ListEmptyComponent` + +Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `ListFooterComponent` + +Rendered at the very end of the list. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | + + + +--- + + +### `SectionSeparatorComponent` + +Rendered at the top and bottom of each section (note this is different from `ItemSeparatorComponent` which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as `ItemSeparatorComponent`. Also receives `highlighted`, `[leading/trailing][Item/Separator]`, and any custom props from `separators.updateProps`. + +| Type | Required | +| - | - | +| any | No | + + + +--- + + +### `extraData` + +A marker property for telling the list to re-render (since it implements `PureComponent`). If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop, stick it here and treat it immutably. + +| Type | Required | +| - | - | +| any | No | + + + +--- + + +### `initialNumToRender` + +How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions. + +| Type | Required | +| - | - | +| number | No | + + + +--- + + +### `inverted` + +Reverses the direction of scroll. Uses scale transforms of `-1`. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `keyExtractor` + +```javascript +(item: object, index: number) => string +``` + +Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like react does. Note that this sets keys for each item, but each overall section still needs its own key. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `onEndReached` + +```javascript +(info: {distanceFromEnd: number}) => void +``` + +Called once when the scroll position gets within `onEndReachedThreshold` of the rendered content. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `onEndReachedThreshold` + + How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the `onEndReached` callback. Thus a value of 0.5 will trigger `onEndReached` when the end of the content is within half the visible length of the list. + +| Type | Required | +| - | - | +| number | No | + + + +--- + + +### `onRefresh` + +```javascript +() => void +``` + +If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the `refreshing` prop correctly. + +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `onViewableItemsChanged` + +```javascript +(info: { + viewableItems: array, + changed: array, + }) => void +``` + +Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop. +| Type | Required | +| - | - | +| function | No | + + + +--- + + +### `refreshing` + +Set this true while waiting for new data from a refresh. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `removeClippedSubviews` + +This may improve scroll performance for large lists. + +> Note: +> May have bugs (missing content) in some circumstances - use at your own risk. + +| Type | Required | +| - | - | +| boolean | No | + + + +--- + + +### `renderSectionHeader` + +``` +(info: {section}) => [element] +``` + +Rendered at the top of each section. These stick to the top of the `ScrollView` by default on iOS. See `stickySectionHeadersEnabled`. + +| Type | Required | +| - | - | +| element | No | + + + +--- + + +### `renderSectionFooter` + +``` +(info: {section}) => [element] +``` + +React element rendered at the bottom of each section. + +| Type | Required | +| - | - | +| element | No | + + + +--- + + +### `stickySectionHeadersEnabled` +Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there. | Type | Required | | - | - | diff --git a/docs/segmentedcontrolios.md b/docs/segmentedcontrolios.md index 749517a97a4d4b..65d764193094a3 100644 --- a/docs/segmentedcontrolios.md +++ b/docs/segmentedcontrolios.md @@ -28,7 +28,7 @@ selects a value and changes the index, as shown in the example below. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`enabled`](docs/segmentedcontrolios.html#enabled) - [`momentary`](docs/segmentedcontrolios.html#momentary) - [`onChange`](docs/segmentedcontrolios.html#onchange) diff --git a/docs/settings.md b/docs/settings.md index 61b539f0bfb43e..9dc2b7e3aa4372 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -33,7 +33,7 @@ previous: pushnotificationios ### `get()` ```javascript -static get(key) +Settings.get(key) ``` @@ -43,7 +43,7 @@ static get(key) ### `set()` ```javascript -static set(settings) +Settings.set(settings) ``` @@ -53,7 +53,7 @@ static set(settings) ### `watchKeys()` ```javascript -static watchKeys(keys, callback) +Settings.watchKeys(keys, callback) ``` @@ -63,7 +63,7 @@ static watchKeys(keys, callback) ### `clearWatch()` ```javascript -static clearWatch(watchId) +Settings.clearWatch(watchId) ``` diff --git a/docs/shadow-props.md b/docs/shadow-props.md index 3514190c4d5f8d..9616d4108aedcd 100644 --- a/docs/shadow-props.md +++ b/docs/shadow-props.md @@ -4,7 +4,7 @@ title: Shadow Props layout: docs category: APIs permalink: docs/shadow-props.html -next: viewproptypes +next: view-props previous: layout-props --- ### Props diff --git a/docs/share.md b/docs/share.md index 8ae16335289b0f..14c359bb6e16fd 100644 --- a/docs/share.md +++ b/docs/share.md @@ -28,15 +28,13 @@ previous: settings ### `share()` ```javascript -static share(content, options) +Share.share(content, options) ``` Open a dialog to share text content. -In iOS, Returns a Promise which will be invoked an object containing `action`, `activityType`. -If the user dismissed the dialog, the Promise will still be resolved with action being `Share.dismissedAction` -and all the other keys being undefined. +In iOS, Returns a Promise which will be invoked an object containing `action`, `activityType`. If the user dismissed the dialog, the Promise will still be resolved with action being `Share.dismissedAction` and all the other keys being undefined. In Android, Returns a Promise which always be resolved with action being `Share.sharedAction`. @@ -64,15 +62,12 @@ At least one of URL and message is required. - `dialogTitle` - - - --- ### `sharedAction()` ```javascript -static sharedAction() +Share.sharedAction() ``` @@ -86,12 +81,15 @@ The content was successfully shared. ### `dismissedAction()` ```javascript -static dismissedAction() +Share.dismissedAction() ``` The dialog has been dismissed. -@platform ios + +| Platform | +| - | +| iOS | diff --git a/docs/slider.md b/docs/slider.md index 32f8eecdcf2d17..c3768149ccfa1a 100644 --- a/docs/slider.md +++ b/docs/slider.md @@ -17,7 +17,7 @@ the state of the root component (`App`). The same component subscribes to the `onValueChange` of `Slider` and changes the value using `setState`. -``` +```javascript import React from 'react'; import { StyleSheet, Text, View, Slider } from 'react-native'; @@ -67,7 +67,7 @@ const styles = StyleSheet.create({ ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`style`](docs/slider.html#style) - [`disabled`](docs/slider.html#disabled) - [`maximumValue`](docs/slider.html#maximumvalue) @@ -103,7 +103,7 @@ Used to style and layout the `Slider`. See `StyleSheet.js` and | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | @@ -274,7 +274,7 @@ leftmost pixel of the image will be stretched to fill the track. | Type | Required | Platform | | - | - | - | -| Image.propTypes.source | No | iOS | +| [Image.propTypes.source](docs/image.html#source) | No | iOS | @@ -289,7 +289,7 @@ rightmost pixel of the image will be stretched to fill the track. | Type | Required | Platform | | - | - | - | -| Image.propTypes.source | No | iOS | +| [Image.propTypes.source](docs/image.html#source) | No | iOS | @@ -303,7 +303,7 @@ Sets an image for the thumb. Only static images are supported. | Type | Required | Platform | | - | - | - | -| Image.propTypes.source | No | iOS | +| [Image.propTypes.source](docs/image.html#source) | No | iOS | @@ -318,7 +318,7 @@ The center pixel of the image will be stretched to fill the track. | Type | Required | Platform | | - | - | - | -| Image.propTypes.source | No | iOS | +| [Image.propTypes.source](docs/image.html#source) | No | iOS | diff --git a/docs/snapshotviewios.md b/docs/snapshotviewios.md index d11f73bb0fb8b4..7048f257a266db 100644 --- a/docs/snapshotviewios.md +++ b/docs/snapshotviewios.md @@ -7,9 +7,10 @@ permalink: docs/snapshotviewios.html next: statusbar previous: slider --- + ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`onSnapshotReady`](docs/snapshotviewios.html#onsnapshotready) - [`testIdentifier`](docs/snapshotviewios.html#testidentifier) diff --git a/docs/statusbar.md b/docs/statusbar.md index ee78f4c85afaa3..e670011c7201df 100644 --- a/docs/statusbar.md +++ b/docs/statusbar.md @@ -35,15 +35,11 @@ mounted. One use case is to specify status bar styles per route using `Navigator ### Imperative API -For cases where using a component is not ideal, there is also an imperative -API exposed as static functions on the component. It is however not recommended -to use the static API and the component for the same prop because any value -set by the static API will get overriden by the one set by the component in -the next render. +For cases where using a component is not ideal, there is also an imperative API exposed as static functions on the component. It is however not recommended to use the static API and the component for the same prop because any value set by the static API will get overriden by the one set by the component in the next render. ### Constants -`currentHeight` (Android only) The height of the status bar. +`currentHeight` (Android only) The current height of the status bar on the device. ### Props @@ -188,17 +184,17 @@ prop. Defaults to 'fade'. ### `setHidden()` ```javascript -static setHidden(hidden: boolean, [animation]: StatusBarAnimation) +StatusBar.setHidden(hidden: boolean, [animation]: StatusBarAnimation) ``` -Show or hide the status bar +Show or hide the status bar. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| hidden | boolean | No | Hide the status bar. | -| animation | [StatusBarAnimation](docs/statusbar.html#statusbaranimation) | Yes | Optional animation when changing the status bar hidden property. | +| hidden | boolean | Yes | Hide the status bar. | +| animation | [StatusBarAnimation](docs/statusbar.html#statusbaranimation) | No | Optional animation when changing the status bar hidden property. | @@ -208,17 +204,17 @@ Show or hide the status bar ### `setBarStyle()` ```javascript -static setBarStyle(style: StatusBarStyle, [animated]: boolean) +StatusBar.setBarStyle(style: StatusBarStyle, [animated]: boolean) ``` -Set the status bar style +Set the status bar style. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| style | [StatusBarStyle](docs/statusbar.html#statusbarstyle) | No | Status bar style to set | -| animated | boolean | Yes | Animate the style change. | +| style | [StatusBarStyle](docs/statusbar.html#statusbarstyle) | Yes | Status bar style to set | +| animated | boolean | No | Animate the style change. | @@ -228,16 +224,16 @@ Set the status bar style ### `setNetworkActivityIndicatorVisible()` ```javascript -static setNetworkActivityIndicatorVisible(visible: boolean) +StatusBar.setNetworkActivityIndicatorVisible(visible: boolean) ``` -Control the visibility of the network activity indicator +Control the visibility of the network activity indicator. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| visible | boolean | No | Show the indicator. | +| visible | boolean | Yes | Show the indicator. | @@ -247,17 +243,17 @@ Control the visibility of the network activity indicator ### `setBackgroundColor()` ```javascript -static setBackgroundColor(color: string, [animated]: boolean) +StatusBar.setBackgroundColor(color: string, [animated]: boolean) ``` -Set the background color for the status bar +Set the background color for the status bar. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| color | string | No | Background color. | -| animated | boolean | Yes | Animate the style change. | +| color | string | Yes | Background color. | +| animated | boolean | No | Animate the style change. | @@ -267,16 +263,16 @@ Set the background color for the status bar ### `setTranslucent()` ```javascript -static setTranslucent(translucent: boolean) +StatusBar.setTranslucent(translucent: boolean) ``` -Control the translucency of the status bar +Control the translucency of the status bar. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| translucent | boolean | No | Set as translucent. | +| translucent | boolean | Yes | Set as translucent. | @@ -307,7 +303,7 @@ Status bar style ### StatusBarAnimation -Status bar animation +Status bar animation. | Type | | - | diff --git a/docs/statusbarios.md b/docs/statusbarios.md index 793f5f4f8db9fe..c0c6d2204bf48d 100644 --- a/docs/statusbarios.md +++ b/docs/statusbarios.md @@ -8,12 +8,4 @@ next: stylesheet previous: share --- -Use `StatusBar` for mutating the status bar. - - - - ---- - -# Reference - +Use [`StatusBar`](docs/statusbar.html) for mutating the status bar. diff --git a/docs/stylesheet.md b/docs/stylesheet.md index 3d3ef03c45ad43..adf546b92ce1d8 100644 --- a/docs/stylesheet.md +++ b/docs/stylesheet.md @@ -54,8 +54,9 @@ subsequent uses are going to refer an id (not implemented yet). ### Methods -- [`setStyleAttributePreprocessor`](docs/stylesheet.html#setstyleattributepreprocessor) - [`create`](docs/stylesheet.html#create) +- [`flatten`](docs/stylesheet.html#flatten) +- [`setStyleAttributePreprocessor`](docs/stylesheet.html#setstyleattributepreprocessor) ### Properties @@ -63,7 +64,6 @@ subsequent uses are going to refer an id (not implemented yet). - [`hairlineWidth`](docs/stylesheet.html#hairlinewidth) - [`absoluteFill`](docs/stylesheet.html#absolutefill) - [`absoluteFillObject`](docs/stylesheet.html#absolutefillobject) -- [`flatten`](docs/stylesheet.html#flatten) @@ -74,51 +74,114 @@ subsequent uses are going to refer an id (not implemented yet). ## Methods -### `setStyleAttributePreprocessor()` +### `create()` ```javascript -static setStyleAttributePreprocessor(property, process) +StyleSheet.create(obj) ``` -WARNING: EXPERIMENTAL. Breaking changes will probably happen a lot and will -not be reliably announced. The whole thing might be deleted, who knows? Use -at your own risk. +Creates a StyleSheet style reference from the given object. -Sets a function to use to pre-process a style property value. This is used -internally to process color and transform values. You should not use this -unless you really know what you are doing and have exhausted other options. +--- +### `flatten()` +```javascript +StyleSheet.flatten(styles) +``` +Flattens an array of style objects, into one aggregated style object. Alternatively, this method can be used to lookup IDs, returned by StyleSheet.register. ---- +> **Note**: +> Exercise caution as abusing this can tax you in terms of optimizations. +> +> IDs enable optimizations through the bridge and memory in general. Refering to style objects directly will deprive you of these optimizations. -### `create()` +Example: ```javascript -static create(obj) +const styles = StyleSheet.create({ + listItem: { + flex: 1, + fontSize: 16, + color: 'white' + }, + selectedListItem: { + color: 'green' + } +}); + +StyleSheet.flatten([styles.listItem, styles.selectedListItem]) +// returns { flex: 1, fontSize: 16, color: 'green' } ``` +Alternative use: -Creates a StyleSheet style reference from the given object. +```javascript +StyleSheet.flatten(styles.listItem); +// return { flex: 1, fontSize: 16, color: 'white' } +// Simply styles.listItem would return its ID (number) +``` + +This method internally uses `StyleSheetRegistry.getStyleByID(style)` to resolve style objects represented by IDs. Thus, an array of style objects (instances of StyleSheet.create), are individually resolved to, their respective objects, merged as one and then returned. This also explains the alternative use. +--- + +### `setStyleAttributePreprocessor()` + +```javascript +StyleSheet.setStyleAttributePreprocessor(property, process) +``` + +> WARNING: EXPERIMENTAL. +> Breaking changes will probably happen a lot and will not be reliably announced. The whole thing might be deleted, who knows? Use at your own risk. + +Sets a function to use to pre-process a style property value. This is used internally to process color and transform values. You should not use this unless you really know what you are doing and have exhausted other options. ## Properties +### `hairlineWidth` +This is defined as the width of a thin line on the platform. It can be used as the thickness of a border or division between two elements. ---- +Example: + +```json +{ + borderBottomColor: '#bbb', + borderBottomWidth: StyleSheet.hairlineWidth +} +``` +This constant will always be a round number of pixels (so a line defined by it look crisp) and will try to match the standard width of a thin line on the underlying platform. However, you should not rely on it being a constant size, because on different platforms and screen densities its value may be calculated differently. +A line with hairline width may not be visible if your simulator is downscaled. --- +### `absoluteFill` + +A very common pattern is to create overlays with position absolute and zero positioning, so `absoluteFill` can be used for convenience and to reduce duplication of these repeated styles. + --- +### `absoluteFillObject` + +Sometimes you may want `absoluteFill` but with a couple tweaks - `absoluteFillObject` can be used to create a customized entry in a `StyleSheet`, e.g.: + +```javascript +const styles = StyleSheet.create({ + wrapper: { + ...StyleSheet.absoluteFillObject, + top: 10, + backgroundColor: 'transparent', + }, +}); +``` diff --git a/docs/switch.md b/docs/switch.md index 6ce1a6f0204fe3..bac4b702f5aab5 100644 --- a/docs/switch.md +++ b/docs/switch.md @@ -9,17 +9,14 @@ previous: statusbar --- Renders a boolean input. -This is a controlled component that requires an `onValueChange` callback that -updates the `value` prop in order for the component to reflect user actions. -If the `value` prop is not updated, the component will continue to render -the supplied `value` prop instead of the expected result of any user actions. +This is a controlled component that requires an `onValueChange` callback that updates the `value` prop in order for the component to reflect user actions. If the `value` prop is not updated, the component will continue to render the supplied `value` prop instead of the expected result of any user actions. @keyword checkbox @keyword toggle ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`disabled`](docs/switch.html#disabled) - [`onTintColor`](docs/switch.html#ontintcolor) - [`onValueChange`](docs/switch.html#onvaluechange) @@ -30,9 +27,6 @@ the supplied `value` prop instead of the expected result of any user actions. - - - --- # Reference diff --git a/docs/systrace.md b/docs/systrace.md index 5e0cd57a6c1f56..30867f5943738a 100644 --- a/docs/systrace.md +++ b/docs/systrace.md @@ -164,12 +164,18 @@ static measureMethods(object, objectName, methodNames) Measures multiple methods of a class. For example, you can do: + +```javascript Systrace.measureMethods(JSON, 'JSON', ['parse', 'stringify']); +``` -@param object -@param objectName -@param methodNames Map from method names to method display names. +**Parameters:** +| Name | Type | Required | Description | +| - | - | - | - | +| object | any | Yes | | +| objectName | string | Yes | | +| methodNames | array | Yes| Map from method names to method display names. | @@ -183,12 +189,19 @@ static measure(objName, fnName, func) Returns an profiled version of the input function. For example, you can: + +```javascript JSON.parse = Systrace.measure('JSON', 'parse', JSON.parse); +``` + +**Parameters:** + +| Name | Type | Required | Description | +| - | - | - | - | +| objName | string | Yes | | +| fnName | string | Yes | | +| func | function | Yes | | -@param objName -@param fnName -@param {function} func -@return {function} replacement function diff --git a/docs/tabbarios-item.md b/docs/tabbarios-item.md index 687ebe1db154a4..981476b16485d1 100644 --- a/docs/tabbarios-item.md +++ b/docs/tabbarios-item.md @@ -7,9 +7,10 @@ permalink: docs/tabbarios-item.html next: text previous: tabbarios --- + ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [ViewPropTypes props...](docs/viewproptypes.html#props) - [`selected`](docs/tabbarios-item.html#selected) - [`badge`](docs/tabbarios-item.html#badge) - [`icon`](docs/tabbarios-item.html#icon) @@ -53,7 +54,7 @@ Little red bubble that sits at the top right of the icon. | Type | Required | | - | - | -| string, ,number | No | +| string, number | No | @@ -121,7 +122,7 @@ icon is defined. If left empty, the icon will be tinted in blue. | Type | Required | | - | - | -| Image.propTypes.source | No | +| [Image.propTypes.source](docs/image.html#source) | No | @@ -134,7 +135,7 @@ React style object. | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | @@ -152,8 +153,6 @@ system ones. | enum('bookmarks', 'contacts', 'downloads', 'favorites', 'featured', 'history', 'more', 'most-recent', 'most-viewed', 'recents', 'search', 'top-rated') | No | - - --- ### `title` diff --git a/docs/tabbarios.md b/docs/tabbarios.md index e8385e0a54dbaf..8c1d83a5321dc1 100644 --- a/docs/tabbarios.md +++ b/docs/tabbarios.md @@ -9,7 +9,7 @@ previous: switch --- ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`barStyle`](docs/tabbarios.html#barstyle) - [`barTintColor`](docs/tabbarios.html#bartintcolor) - [`itemPositioning`](docs/tabbarios.html#itempositioning) @@ -61,12 +61,10 @@ Background color of the tab bar ### `itemPositioning` Specifies tab bar item positioning. Available values are: -- fill - distributes items across the entire width of the tab bar -- center - centers item in the available tab bar space -- auto (default) - distributes items dynamically according to the -user interface idiom. In a horizontally compact environment (e.g. iPhone 5) -this value defaults to `fill`, in a horizontally regular one (e.g. iPad) -it defaults to center. + +- `fill` - distributes items across the entire width of the tab bar +- `center` - centers item in the available tab bar space +- `auto` (default) - distributes items dynamically according to the user interface idiom. In a horizontally compact environment (e.g. iPhone 5) this value defaults to `fill`, in a horizontally regular one (e.g. iPad) it defaults to center. | Type | Required | | - | - | @@ -83,7 +81,7 @@ it defaults to center. | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | diff --git a/docs/textstyleproptypes.md b/docs/text-style-props.md similarity index 67% rename from docs/textstyleproptypes.md rename to docs/text-style-props.md index c4f6def481bda1..72bf702655e0fb 100644 --- a/docs/textstyleproptypes.md +++ b/docs/text-style-props.md @@ -1,32 +1,32 @@ --- -id: textstyleproptypes -title: TextStylePropTypes +id: text-style-props +title: Text Style Props layout: docs category: APIs -permalink: docs/textstyleproptypes.html -next: imagestyleproptypes -previous: viewstyleproptypes +permalink: docs/text-style-props.html +next: image-style-props +previous: view-style-props --- ### Props -- [`textShadowOffset`](docs/textstyleproptypes.html#textshadowoffset) -- [`color`](docs/textstyleproptypes.html#color) -- [`fontSize`](docs/textstyleproptypes.html#fontsize) -- [`fontStyle`](docs/textstyleproptypes.html#fontstyle) -- [`fontWeight`](docs/textstyleproptypes.html#fontweight) -- [`lineHeight`](docs/textstyleproptypes.html#lineheight) -- [`textAlign`](docs/textstyleproptypes.html#textalign) -- [`textDecorationLine`](docs/textstyleproptypes.html#textdecorationline) -- [`textShadowColor`](docs/textstyleproptypes.html#textshadowcolor) -- [`fontFamily`](docs/textstyleproptypes.html#fontfamily) -- [`textShadowRadius`](docs/textstyleproptypes.html#textshadowradius) -- [`includeFontPadding`](docs/textstyleproptypes.html#includefontpadding) -- [`textAlignVertical`](docs/textstyleproptypes.html#textalignvertical) -- [`fontVariant`](docs/textstyleproptypes.html#fontvariant) -- [`letterSpacing`](docs/textstyleproptypes.html#letterspacing) -- [`textDecorationColor`](docs/textstyleproptypes.html#textdecorationcolor) -- [`textDecorationStyle`](docs/textstyleproptypes.html#textdecorationstyle) -- [`writingDirection`](docs/textstyleproptypes.html#writingdirection) +- [`textShadowOffset`](docs/text-style-props.html#textshadowoffset) +- [`color`](docs/text-style-props.html#color) +- [`fontSize`](docs/text-style-props.html#fontsize) +- [`fontStyle`](docs/text-style-props.html#fontstyle) +- [`fontWeight`](docs/text-style-props.html#fontweight) +- [`lineHeight`](docs/text-style-props.html#lineheight) +- [`textAlign`](docs/text-style-props.html#textalign) +- [`textDecorationLine`](docs/text-style-props.html#textdecorationline) +- [`textShadowColor`](docs/text-style-props.html#textshadowcolor) +- [`fontFamily`](docs/text-style-props.html#fontfamily) +- [`textShadowRadius`](docs/text-style-props.html#textshadowradius) +- [`includeFontPadding`](docs/text-style-props.html#includefontpadding) +- [`textAlignVertical`](docs/text-style-props.html#textalignvertical) +- [`fontVariant`](docs/text-style-props.html#fontvariant) +- [`letterSpacing`](docs/text-style-props.html#letterspacing) +- [`textDecorationColor`](docs/text-style-props.html#textdecorationcolor) +- [`textDecorationStyle`](docs/text-style-props.html#textdecorationstyle) +- [`writingDirection`](docs/text-style-props.html#writingdirection) diff --git a/docs/text.md b/docs/text.md index 2f43c52ede2cd9..b64199adea98d4 100644 --- a/docs/text.md +++ b/docs/text.md @@ -7,6 +7,7 @@ permalink: docs/text.html next: textinput previous: tabbarios-item --- + A React component for displaying text. `Text` supports nesting, styling, and touch handling. diff --git a/docs/textinput.md b/docs/textinput.md index 75ad2ca91c2ced..e032d386c703bb 100644 --- a/docs/textinput.md +++ b/docs/textinput.md @@ -118,7 +118,7 @@ or control this param programmatically with native code. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`placeholderTextColor`](docs/textinput.html#placeholdertextcolor) - [`allowFontScaling`](docs/textinput.html#allowfontscaling) - [`autoCorrect`](docs/textinput.html#autocorrect) diff --git a/docs/timepickerandroid.md b/docs/timepickerandroid.md index 570dfc1566e363..24e877aa8e2506 100644 --- a/docs/timepickerandroid.md +++ b/docs/timepickerandroid.md @@ -46,7 +46,7 @@ try { ### `open()` ```javascript -static open(options) +TimePickerAndroid.open(options) ``` @@ -76,7 +76,7 @@ being undefined. **Always** check whether the `action` before reading the values ### `timeSetAction()` ```javascript -static timeSetAction() +TimePickerAndroid.timeSetAction() ``` @@ -90,7 +90,7 @@ A time has been selected. ### `dismissedAction()` ```javascript -static dismissedAction() +TimePickerAndroid.dismissedAction() ``` diff --git a/docs/toastandroid.md b/docs/toastandroid.md index a8408b17e98559..ecb15135bf148d 100644 --- a/docs/toastandroid.md +++ b/docs/toastandroid.md @@ -21,6 +21,7 @@ The 'showWithGravityAndOffset' function adds on the ability to specify offset These offset values will translate to pixels. Basic usage: + ```javascript ToastAndroid.show('A pikachu appeared nearby !', ToastAndroid.SHORT); ToastAndroid.showWithGravity('All Your Base Are Belong To Us', ToastAndroid.SHORT, ToastAndroid.CENTER); @@ -55,7 +56,7 @@ ToastAndroid.showWithGravityAndOffset('A wild toast appeared!', ToastAndroid.LON ### `show()` ```javascript -static show(message, duration) +ToastAndroid.show(message, duration) ``` @@ -65,7 +66,7 @@ static show(message, duration) ### `showWithGravity()` ```javascript -static showWithGravity(message, duration, gravity) +ToastAndroid.showWithGravity(message, duration, gravity) ``` @@ -75,28 +76,30 @@ static showWithGravity(message, duration, gravity) ### `showWithGravityAndOffset()` ```javascript -static showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset) +ToastAndroid.showWithGravityAndOffset(message, duration, gravity, xOffset, yOffset) ``` ## Properties - +### `SHORT` --- - +### `LONG` --- - +### `TOP` --- +### `BOTTOM` --- +### `CENTER` diff --git a/docs/toolbarandroid.md b/docs/toolbarandroid.md index 17bdc46c6e75fa..ba37cb65c903e9 100644 --- a/docs/toolbarandroid.md +++ b/docs/toolbarandroid.md @@ -43,7 +43,7 @@ onActionSelected: function(position) { ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`overflowIcon`](docs/toolbarandroid.html#overflowicon) - [`actions`](docs/toolbarandroid.html#actions) - [`contentInsetStart`](docs/toolbarandroid.html#contentinsetstart) diff --git a/docs/touchablehighlight.md b/docs/touchablehighlight.md index cbaaf3222d27b9..2842c41a2f3282 100644 --- a/docs/touchablehighlight.md +++ b/docs/touchablehighlight.md @@ -169,7 +169,7 @@ Called immediately after the underlay is shown | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | diff --git a/docs/touchablenativefeedback.md b/docs/touchablenativefeedback.md index 1e21ad203017be..a821eebeb31b06 100644 --- a/docs/touchablenativefeedback.md +++ b/docs/touchablenativefeedback.md @@ -99,11 +99,10 @@ fallback to background. ### `SelectableBackground()` ```javascript -static SelectableBackground() +TouchableNativeFeedback.SelectableBackground() ``` -Creates an object that represents android theme's default background for -selectable elements (?android:attr/selectableItemBackground). +Creates an object that represents android theme's default background for selectable elements (?android:attr/selectableItemBackground). @@ -112,11 +111,10 @@ selectable elements (?android:attr/selectableItemBackground). ### `SelectableBackgroundBorderless()` ```javascript -static SelectableBackgroundBorderless() +TouchableNativeFeedback.SelectableBackgroundBorderless() ``` -Creates an object that represent android theme's default background for borderless -selectable elements (?android:attr/selectableItemBackgroundBorderless). +Creates an object that represent android theme's default background for borderless selectable elements (?android:attr/selectableItemBackgroundBorderless). Available on android API level 21+. @@ -126,21 +124,17 @@ Available on android API level 21+. ### `Ripple()` ```javascript -static Ripple(color: string, borderless: boolean) +TouchableNativeFeedback.Ripple(color: string, borderless: boolean) ``` -Creates an object that represents ripple drawable with specified color (as a -string). If property `borderless` evaluates to true the ripple will -render outside of the view bounds (see native actionbar buttons as an -example of that behavior). This background type is available on Android -API level 21+. +Creates an object that represents ripple drawable with specified color (as a string). If property `borderless` evaluates to true the ripple will render outside of the view bounds (see native actionbar buttons as an example of that behavior). This background type is available on Android API level 21+. **Parameters:** | Name | Type | Required | Description | | - | - | - | - | -| color | string | No | The ripple color | -| borderless | boolean | No | If the ripple can render outside it's bounds | +| color | string | Yes | The ripple color | +| borderless | boolean | Yes | If the ripple can render outside its bounds | @@ -150,8 +144,8 @@ API level 21+. ### `canUseNativeForeground()` ```javascript -static canUseNativeForeground() +TouchableNativeFeedback.canUseNativeForeground() ``` - +Whether native foreground ripple is available on the current version of Android. diff --git a/docs/touchablewithoutfeedback.md b/docs/touchablewithoutfeedback.md index 6ac830f1ffdf02..e352798d791378 100644 --- a/docs/touchablewithoutfeedback.md +++ b/docs/touchablewithoutfeedback.md @@ -48,12 +48,10 @@ If you wish to have several child components, wrap them in a View. ### `hitSlop` -This defines how far your touch can start away from the button. This is -added to `pressRetentionOffset` when moving off of the button. -** NOTE ** -The touch area never extends past the parent view bounds and the Z-index -of sibling views always takes precedence if a touch hits two overlapping -views. +This defines how far your touch can start away from the button. This is added to `pressRetentionOffset` when moving off of the button. + +> Note: +> The touch area never extends past the parent view bounds and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. | Type | Required | | - | - | diff --git a/docs/vibration.md b/docs/vibration.md index c19e27c2d9e380..ca49bab23ac532 100644 --- a/docs/vibration.md +++ b/docs/vibration.md @@ -63,7 +63,7 @@ Vibration.cancel() ### `vibrate()` ```javascript -static vibrate(pattern: number, Array, repeat: boolean) +Vibration.vibrate(pattern: number, Array, repeat: boolean) ``` Trigger a vibration with specified `pattern`. @@ -72,8 +72,8 @@ Trigger a vibration with specified `pattern`. | Name | Type | Required | Description | | - | - | - | - | -| pattern | number,Array | No | Vibration pattern, accept a number or an array of number. Default to 400ms. | -| repeat | boolean | No | Optional. Repeat vibration pattern until cancel(), default to false. | +| pattern | number, Array | Yes | Vibration pattern, accept a number or an array of number. Default to 400ms. | +| repeat | boolean | Yes | Optional. Repeat vibration pattern until cancel(), default to false. | @@ -83,13 +83,11 @@ Trigger a vibration with specified `pattern`. ### `cancel()` ```javascript -static cancel() -``` - -Stop vibration -``` Vibration.cancel() ``` +Stop vibration. + + diff --git a/docs/vibrationios.md b/docs/vibrationios.md index ba4a175a67e64d..e2452907caaabd 100644 --- a/docs/vibrationios.md +++ b/docs/vibrationios.md @@ -8,18 +8,15 @@ next: layout-props previous: vibration --- -NOTE: `VibrationIOS` is being deprecated. Use `Vibration` instead. +> NOTE: +> `VibrationIOS` is deprecated. Use [`Vibration`](docs/vibration.html) instead. -The Vibration API is exposed at `VibrationIOS.vibrate()`. On iOS, calling this -function will trigger a one second vibration. The vibration is asynchronous -so this method will return immediately. +The Vibration API is exposed at `VibrationIOS.vibrate()`. On iOS, calling this function will trigger a one second vibration. The vibration is asynchronous so this method will return immediately. -There will be no effect on devices that do not support Vibration, eg. the iOS -simulator. +There will be no effect on devices that do not support Vibration, eg. the iOS simulator. Vibration patterns are currently unsupported. - ### Methods - [`vibrate`](docs/vibrationios.html#vibrate) @@ -36,11 +33,10 @@ Vibration patterns are currently unsupported. ### `vibrate()` ```javascript -static vibrate() +VibrationIOS.vibrate() ``` - -@deprecated +**Deprecated.** diff --git a/docs/viewproptypes.md b/docs/view-props.md similarity index 86% rename from docs/viewproptypes.md rename to docs/view-props.md index 304ebc34a7c84c..3ab3c2b3cd1c4e 100644 --- a/docs/viewproptypes.md +++ b/docs/view-props.md @@ -1,44 +1,44 @@ --- -id: viewproptypes -title: ViewPropTypes +id: view-props +title: View Props layout: docs category: APIs -permalink: docs/viewproptypes.html -next: viewstyleproptypes +permalink: docs/view-props.html +next: view-style-props previous: shadow-props --- ### Props -- [`onStartShouldSetResponder`](docs/viewproptypes.html#onstartshouldsetresponder) -- [`accessibilityLabel`](docs/viewproptypes.html#accessibilitylabel) -- [`hitSlop`](docs/viewproptypes.html#hitslop) -- [`nativeID`](docs/viewproptypes.html#nativeid) -- [`onAccessibilityTap`](docs/viewproptypes.html#onaccessibilitytap) -- [`onLayout`](docs/viewproptypes.html#onlayout) -- [`onMagicTap`](docs/viewproptypes.html#onmagictap) -- [`onMoveShouldSetResponder`](docs/viewproptypes.html#onmoveshouldsetresponder) -- [`onMoveShouldSetResponderCapture`](docs/viewproptypes.html#onmoveshouldsetrespondercapture) -- [`onResponderGrant`](docs/viewproptypes.html#onrespondergrant) -- [`onResponderMove`](docs/viewproptypes.html#onrespondermove) -- [`onResponderReject`](docs/viewproptypes.html#onresponderreject) -- [`onResponderRelease`](docs/viewproptypes.html#onresponderrelease) -- [`onResponderTerminate`](docs/viewproptypes.html#onresponderterminate) -- [`onResponderTerminationRequest`](docs/viewproptypes.html#onresponderterminationrequest) -- [`accessible`](docs/viewproptypes.html#accessible) -- [`onStartShouldSetResponderCapture`](docs/viewproptypes.html#onstartshouldsetrespondercapture) -- [`pointerEvents`](docs/viewproptypes.html#pointerevents) -- [`removeClippedSubviews`](docs/viewproptypes.html#removeclippedsubviews) -- [`style`](docs/viewproptypes.html#style) -- [`testID`](docs/viewproptypes.html#testid) -- [`accessibilityComponentType`](docs/viewproptypes.html#accessibilitycomponenttype) -- [`accessibilityLiveRegion`](docs/viewproptypes.html#accessibilityliveregion) -- [`collapsable`](docs/viewproptypes.html#collapsable) -- [`importantForAccessibility`](docs/viewproptypes.html#importantforaccessibility) -- [`needsOffscreenAlphaCompositing`](docs/viewproptypes.html#needsoffscreenalphacompositing) -- [`renderToHardwareTextureAndroid`](docs/viewproptypes.html#rendertohardwaretextureandroid) -- [`accessibilityTraits`](docs/viewproptypes.html#accessibilitytraits) -- [`accessibilityViewIsModal`](docs/viewproptypes.html#accessibilityviewismodal) -- [`shouldRasterizeIOS`](docs/viewproptypes.html#shouldrasterizeios) +- [`onStartShouldSetResponder`](docs/view-props.html#onstartshouldsetresponder) +- [`accessibilityLabel`](docs/view-props.html#accessibilitylabel) +- [`hitSlop`](docs/view-props.html#hitslop) +- [`nativeID`](docs/view-props.html#nativeid) +- [`onAccessibilityTap`](docs/view-props.html#onaccessibilitytap) +- [`onLayout`](docs/view-props.html#onlayout) +- [`onMagicTap`](docs/view-props.html#onmagictap) +- [`onMoveShouldSetResponder`](docs/view-props.html#onmoveshouldsetresponder) +- [`onMoveShouldSetResponderCapture`](docs/view-props.html#onmoveshouldsetrespondercapture) +- [`onResponderGrant`](docs/view-props.html#onrespondergrant) +- [`onResponderMove`](docs/view-props.html#onrespondermove) +- [`onResponderReject`](docs/view-props.html#onresponderreject) +- [`onResponderRelease`](docs/view-props.html#onresponderrelease) +- [`onResponderTerminate`](docs/view-props.html#onresponderterminate) +- [`onResponderTerminationRequest`](docs/view-props.html#onresponderterminationrequest) +- [`accessible`](docs/view-props.html#accessible) +- [`onStartShouldSetResponderCapture`](docs/view-props.html#onstartshouldsetrespondercapture) +- [`pointerEvents`](docs/view-props.html#pointerevents) +- [`removeClippedSubviews`](docs/view-props.html#removeclippedsubviews) +- [`style`](docs/view-props.html#style) +- [`testID`](docs/view-props.html#testid) +- [`accessibilityComponentType`](docs/view-props.html#accessibilitycomponenttype) +- [`accessibilityLiveRegion`](docs/view-props.html#accessibilityliveregion) +- [`collapsable`](docs/view-props.html#collapsable) +- [`importantForAccessibility`](docs/view-props.html#importantforaccessibility) +- [`needsOffscreenAlphaCompositing`](docs/view-props.html#needsoffscreenalphacompositing) +- [`renderToHardwareTextureAndroid`](docs/view-props.html#rendertohardwaretextureandroid) +- [`accessibilityTraits`](docs/view-props.html#accessibilitytraits) +- [`accessibilityViewIsModal`](docs/view-props.html#accessibilityviewismodal) +- [`shouldRasterizeIOS`](docs/view-props.html#shouldrasterizeios) @@ -399,7 +399,7 @@ subviews must also have `overflow: hidden`, as should the containing view | Type | Required | | - | - | -| stylePropType | No | +| style | No | diff --git a/docs/viewstyleproptypes.md b/docs/view-style-props.md similarity index 58% rename from docs/viewstyleproptypes.md rename to docs/view-style-props.md index 08bd57386e8035..b369582d5c4960 100644 --- a/docs/viewstyleproptypes.md +++ b/docs/view-style-props.md @@ -1,40 +1,40 @@ --- -id: viewstyleproptypes -title: ViewStylePropTypes +id: view-style-props +title: View Style Props layout: docs category: APIs -permalink: docs/viewstyleproptypes.html -next: textstyleproptypes -previous: viewproptypes +permalink: docs/view-style-props.html +next: text-style-props +previous: view-props --- ### Props -- [`borderRightColor`](docs/viewstyleproptypes.html#borderrightcolor) -- [`backfaceVisibility`](docs/viewstyleproptypes.html#backfacevisibility) -- [`borderBottomColor`](docs/viewstyleproptypes.html#borderbottomcolor) -- [`borderBottomEndRadius`](docs/viewstyleproptypes.html#borderbottomendradius) -- [`borderBottomLeftRadius`](docs/viewstyleproptypes.html#borderbottomleftradius) -- [`borderBottomRightRadius`](docs/viewstyleproptypes.html#borderbottomrightradius) -- [`borderBottomStartRadius`](docs/viewstyleproptypes.html#borderbottomstartradius) -- [`borderBottomWidth`](docs/viewstyleproptypes.html#borderbottomwidth) -- [`borderColor`](docs/viewstyleproptypes.html#bordercolor) -- [`borderEndColor`](docs/viewstyleproptypes.html#borderendcolor) -- [`borderLeftColor`](docs/viewstyleproptypes.html#borderleftcolor) -- [`borderLeftWidth`](docs/viewstyleproptypes.html#borderleftwidth) -- [`borderRadius`](docs/viewstyleproptypes.html#borderradius) -- [`backgroundColor`](docs/viewstyleproptypes.html#backgroundcolor) -- [`borderRightWidth`](docs/viewstyleproptypes.html#borderrightwidth) -- [`borderStartColor`](docs/viewstyleproptypes.html#borderstartcolor) -- [`borderStyle`](docs/viewstyleproptypes.html#borderstyle) -- [`borderTopColor`](docs/viewstyleproptypes.html#bordertopcolor) -- [`borderTopEndRadius`](docs/viewstyleproptypes.html#bordertopendradius) -- [`borderTopLeftRadius`](docs/viewstyleproptypes.html#bordertopleftradius) -- [`borderTopRightRadius`](docs/viewstyleproptypes.html#bordertoprightradius) -- [`borderTopStartRadius`](docs/viewstyleproptypes.html#bordertopstartradius) -- [`borderTopWidth`](docs/viewstyleproptypes.html#bordertopwidth) -- [`borderWidth`](docs/viewstyleproptypes.html#borderwidth) -- [`opacity`](docs/viewstyleproptypes.html#opacity) -- [`elevation`](docs/viewstyleproptypes.html#elevation) +- [`borderRightColor`](docs/view-style-props.html#borderrightcolor) +- [`backfaceVisibility`](docs/view-style-props.html#backfacevisibility) +- [`borderBottomColor`](docs/view-style-props.html#borderbottomcolor) +- [`borderBottomEndRadius`](docs/view-style-props.html#borderbottomendradius) +- [`borderBottomLeftRadius`](docs/view-style-props.html#borderbottomleftradius) +- [`borderBottomRightRadius`](docs/view-style-props.html#borderbottomrightradius) +- [`borderBottomStartRadius`](docs/view-style-props.html#borderbottomstartradius) +- [`borderBottomWidth`](docs/view-style-props.html#borderbottomwidth) +- [`borderColor`](docs/view-style-props.html#bordercolor) +- [`borderEndColor`](docs/view-style-props.html#borderendcolor) +- [`borderLeftColor`](docs/view-style-props.html#borderleftcolor) +- [`borderLeftWidth`](docs/view-style-props.html#borderleftwidth) +- [`borderRadius`](docs/view-style-props.html#borderradius) +- [`backgroundColor`](docs/view-style-props.html#backgroundcolor) +- [`borderRightWidth`](docs/view-style-props.html#borderrightwidth) +- [`borderStartColor`](docs/view-style-props.html#borderstartcolor) +- [`borderStyle`](docs/view-style-props.html#borderstyle) +- [`borderTopColor`](docs/view-style-props.html#bordertopcolor) +- [`borderTopEndRadius`](docs/view-style-props.html#bordertopendradius) +- [`borderTopLeftRadius`](docs/view-style-props.html#bordertopleftradius) +- [`borderTopRightRadius`](docs/view-style-props.html#bordertoprightradius) +- [`borderTopStartRadius`](docs/view-style-props.html#bordertopstartradius) +- [`borderTopWidth`](docs/view-style-props.html#bordertopwidth) +- [`borderWidth`](docs/view-style-props.html#borderwidth) +- [`opacity`](docs/view-style-props.html#opacity) +- [`elevation`](docs/view-style-props.html#elevation) diff --git a/docs/view.md b/docs/view.md index f381c132b1836e..c00b327a440a68 100644 --- a/docs/view.md +++ b/docs/view.md @@ -7,17 +7,12 @@ permalink: docs/view.html next: viewpagerandroid previous: touchablewithoutfeedback --- -The most fundamental component for building a UI, `View` is a container that supports layout with -[flexbox](docs/flexbox.html), [style](docs/style.html), -[some touch handling](docs/handling-touches.html), and -[accessibility](docs/accessibility.html) controls. `View` maps directly to the -native view equivalent on whatever platform React Native is running on, whether that is a -`UIView`, `
`, `android.view`, etc. + +The most fundamental component for building a UI, `View` is a container that supports layout with [flexbox](docs/flexbox.html), [style](docs/style.html), [some touch handling](docs/handling-touches.html), and [accessibility](docs/accessibility.html) controls. `View` maps directly to the native view equivalent on whatever platform React Native is running on, whether that is a `UIView`, `
`, `android.view`, etc. `View` is designed to be nested inside other views and can have 0 to many children of any type. -This example creates a `View` that wraps two colored boxes and a text component in a row with -padding. +This example creates a `View` that wraps two colored boxes and a text component in a row with padding. ```javascript class ViewColoredBoxesWithText extends Component { @@ -33,13 +28,11 @@ class ViewColoredBoxesWithText extends Component { } ``` -> `View`s are designed to be used with [`StyleSheet`](docs/style.html) for clarity -> and performance, although inline styles are also supported. +> `View`s are designed to be used with [`StyleSheet`](docs/style.html) for clarity and performance, although inline styles are also supported. ### Synthetic Touch Events -For `View` responder props (e.g., `onResponderMove`), the synthetic touch event passed to them -are of the following form: +For `View` responder props (e.g., `onResponderMove`), the synthetic touch event passed to them are of the following form: - `nativeEvent` - `changedTouches` - Array of all touch events that have changed since the last event. @@ -54,7 +47,7 @@ are of the following form: ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`onStartShouldSetResponder`](docs/view.html#onstartshouldsetresponder) - [`accessibilityLabel`](docs/view.html#accessibilitylabel) - [`hitSlop`](docs/view.html#hitslop) diff --git a/docs/viewpagerandroid.md b/docs/viewpagerandroid.md index 0288ea25b6a6f2..8b4006445f33db 100644 --- a/docs/viewpagerandroid.md +++ b/docs/viewpagerandroid.md @@ -49,7 +49,7 @@ var styles = { ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`initialPage`](docs/viewpagerandroid.html#initialpage) - [`keyboardDismissMode`](docs/viewpagerandroid.html#keyboarddismissmode) - [`onPageScroll`](docs/viewpagerandroid.html#onpagescroll) @@ -92,8 +92,9 @@ update the page, and `onPageSelected` to monitor page changes ### `keyboardDismissMode` Determines whether the keyboard gets dismissed in response to a drag. - - 'none' (the default), drags do not dismiss the keyboard. - - 'on-drag', the keyboard is dismissed when a drag begins. + +- 'none' (the default), drags do not dismiss the keyboard. +- 'on-drag', the keyboard is dismissed when a drag begins. | Type | Required | | - | - | @@ -106,13 +107,11 @@ Determines whether the keyboard gets dismissed in response to a drag. ### `onPageScroll` -Executed when transitioning between pages (ether because of animation for -the requested page change or when user is swiping/dragging between pages) -The `event.nativeEvent` object for this callback will carry following data: - - position - index of first page from the left that is currently visible - - offset - value from range [0,1) describing stage between page transitions. - Value x means that (1 - x) fraction of the page at "position" index is - visible, and x fraction of the next page is visible. +Executed when transitioning between pages (ether because of animation for the requested page change or when user is swiping/dragging between pages) The `event.nativeEvent` object for this callback will carry following data: + +- position - index of first page from the left that is currently visible +- offset - value from range [0,1) describing stage between page transitions. + Value x means that (1 - x) fraction of the page at "position" index is visible, and x fraction of the next page is visible. | Type | Required | | - | - | diff --git a/docs/virtualizedlist.md b/docs/virtualizedlist.md index 6d4054ba18c76b..016eee879545ff 100644 --- a/docs/virtualizedlist.md +++ b/docs/virtualizedlist.md @@ -7,48 +7,59 @@ permalink: docs/virtualizedlist.html next: webview previous: viewpagerandroid --- -Base implementation for the more convenient [``](/react-native/docs/flatlist.html) -and [``](/react-native/docs/sectionlist.html) components, which are also better -documented. In general, this should only really be used if you need more flexibility than -`FlatList` provides, e.g. for use with immutable data instead of plain arrays. -Virtualization massively improves memory consumption and performance of large lists by -maintaining a finite render window of active items and replacing all items outside of the render -window with appropriately sized blank space. The window adapts to scrolling behavior, and items -are rendered incrementally with low-pri (after any running interactions) if they are far from the -visible area, or with hi-pri otherwise to minimize the potential of seeing blank space. +Base implementation for the more convenient [``](/react-native/docs/flatlist.html) and [``](/react-native/docs/sectionlist.html) components, which are also better documented. In general, this should only really be used if you need more flexibility than `FlatList` provides, e.g. for use with immutable data instead of plain arrays. + +Virtualization massively improves memory consumption and performance of large lists by maintaining a finite render window of active items and replacing all items outside of the render window with appropriately sized blank space. The window adapts to scrolling behavior, and items are rendered incrementally with low-pri (after any running interactions) if they are far from the visible area, or with hi-pri otherwise to minimize the potential of seeing blank space. Some caveats: -- Internal state is not preserved when content scrolls out of the render window. Make sure all - your data is captured in the item data or external stores like Flux, Redux, or Relay. -- This is a `PureComponent` which means that it will not re-render if `props` remain shallow- - equal. Make sure that everything your `renderItem` function depends on is passed as a prop - (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on - changes. This includes the `data` prop and parent component state. -- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously - offscreen. This means it's possible to scroll faster than the fill rate ands momentarily see - blank content. This is a tradeoff that can be adjusted to suit the needs of each application, - and we are working on improving it behind the scenes. -- By default, the list looks for a `key` prop on each item and uses that for the React key. - Alternatively, you can provide a custom `keyExtractor` prop. +- Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay. +- This is a `PureComponent` which means that it will not re-render if `props` remain shallow-equal. Make sure that everything your `renderItem` function depends on is passed as a prop (e.g. `extraData`) that is not `===` after updates, otherwise your UI may not update on changes. This includes the `data` prop and parent component state. +- In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate ands momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes. +- By default, the list looks for a `key` prop on each item and uses that for the React key. Alternatively, you can provide a custom `keyExtractor` prop. ### Props -- [`last`](docs/virtualizedlist.html#last) -- [`first`](docs/virtualizedlist.html#first) +- [`ScrollView` props...](docs/scrollview.html#props) +- [`renderItem`](docs/virtualizedlist.html#renderitem) +- [`data`](docs/virtualizedlist.html#data) +- [`getItem`](docs/virtualizedlist.html#getitem) +- [`getItemCount`](docs/virtualizedlist.html#getitemcount) +- [`debug`](docs/virtualizedlist.html#debug) +- [`extraData`](docs/virtualizedlist.html#extradata) +- [`getItemLayout`](docs/virtualizedlist.html#getitemlayout) +- [`initialScrollIndex`](docs/virtualizedlist.html#initialscrollindex) +- [`inverted`](docs/virtualizedlist.html#inverted) +- [`CellRendererComponent`](docs/virtualizedlist.html#cellrenderercomponent) +- [`ListEmptyComponent`](docs/virtualizedlist.html#listemptycomponent) +- [`ListFooterComponent`](docs/virtualizedlist.html#listfootercomponent) +- [`ListHeaderComponent`](docs/virtualizedlist.html#listheadercomponent) +- [`onEndReached`](docs/virtualizedlist.html#onendreached) +- [`onLayout`](docs/virtualizedlist.html#onlayout) +- [`onRefresh`](docs/virtualizedlist.html#onrefresh) +- [`onScrollToIndexFailed`](docs/virtualizedlist.html#onscrolltoindexfailed) +- [`onViewableItemsChanged`](docs/virtualizedlist.html#onviewableitemschanged) +- [`refreshing`](docs/virtualizedlist.html#refreshing) +- [`removeClippedSubviews`](docs/virtualizedlist.html#removeclippedsubviews) +- [`renderScrollComponent`](docs/virtualizedlist.html#renderscrollcomponent) +- [`viewabilityConfig`](docs/virtualizedlist.html#viewabilityconfig) +- [`viewabilityConfigCallbackPairs`](docs/virtualizedlist.html#viewabilityconfigcallbackpairs) - [`horizontal`](docs/virtualizedlist.html#horizontal) - [`initialNumToRender`](docs/virtualizedlist.html#initialnumtorender) - [`keyExtractor`](docs/virtualizedlist.html#keyextractor) -- [`disableVirtualization`](docs/virtualizedlist.html#disablevirtualization) - [`maxToRenderPerBatch`](docs/virtualizedlist.html#maxtorenderperbatch) - [`onEndReachedThreshold`](docs/virtualizedlist.html#onendreachedthreshold) - [`scrollEventThrottle`](docs/virtualizedlist.html#scrolleventthrottle) - [`updateCellsBatchingPeriod`](docs/virtualizedlist.html#updatecellsbatchingperiod) - [`windowSize`](docs/virtualizedlist.html#windowsize) +- [`disableVirtualization`](docs/virtualizedlist.html#disablevirtualization) +- [`progressViewOffset`](docs/virtualizedlist.html#progressviewoffset) +### State - +- [`first`](docs/virtualizedlist.html#first) +- [`last`](docs/virtualizedlist.html#last) ### Methods @@ -74,104 +85,384 @@ Some caveats: ## Props -### `last` +### `renderItem` + +| Type | Required | +| - | - | +| number | Yes | + + +--- +### `data` + +The default accessor functions assume this is an array of objects with shape `{key: string}` but you can override `getItem`, `getItemCount`, and `keyExtractor` to handle any type of index-based data. | Type | Required | | - | - | -| number | Yes | +| any | Yes | + + +--- + + +### `getItem` + +```javascript +(data: any, index: number) => object +``` +A generic accessor for extracting an item from any sort of data blob. +| Type | Required | +| - | - | +| function | Yes | --- -### `first` +### `getItemCount` + +```javascript +(data: any) => number +``` +Determines how many items are in the data blob. | Type | Required | | - | - | -| number | Yes | +| function | Yes | + + +--- +### `debug` + +`debug` will turn on extra logging and visual overlays to aid with debugging both usage and implementation, but with a significant perf hit. + +| Type | Required | +| - | - | +| boolean | No | + --- -### `horizontal` +### `extraData` +A marker property for telling the list to re-render (since it implements `PureComponent`). If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop, stick it here and treat it immutably. | Type | Required | | - | - | -| | No | +| any | No | + + +--- + + +### `getItemLayout` +```javascript +( + data: any, + index: number, + ) => {length: number, offset: number, index: number} +``` +| Type | Required | +| - | - | +| function | No | --- -### `initialNumToRender` +### `initialScrollIndex` +Instead of starting at the top with the first item, start at `initialScrollIndex`. This disables the "scroll to top" optimization that keeps the first `initialNumToRender` items always rendered and immediately renders the items starting at this initial index. Requires `getItemLayout` to be implemented. | Type | Required | | - | - | -| | No | +| number | No | + + +--- + +### `inverted` +Reverses the direction of scroll. Uses scale transforms of -1. + +| Type | Required | +| - | - | +| boolean | No | --- -### `keyExtractor` +### `CellRendererComponent` +Each cell is rendered using this element. Can be a React Component Class,or a render function. Defaults to using [`View`](docs/view.html). | Type | Required | | - | - | -| | No | +| component, function | No | + +--- + + +### `ListEmptyComponent` + +Rendered when the list is empty. Can be a React Component Class, a render function, or a rendered element. +| Type | Required | +| - | - | +| component, function, element | No | --- -### `disableVirtualization` +### `ListFooterComponent` +Rendered at the bottom of all the items. Can be a React Component Class, a render function, or a rendered element. | Type | Required | | - | - | -| | No | +| component, function, element | No | +--- + + +### `ListHeaderComponent` + +Rendered at the top of all the items. Can be a React Component Class, a render function, or a rendered element. + +| Type | Required | +| - | - | +| component, function, element | No | --- -### `maxToRenderPerBatch` +### `onLayout` +| Type | Required | +| - | - | +| function | No | + + +--- + + +### `onRefresh` + +```javascript +() => void +``` + +If provided, a standard `RefreshControl` will be added for "Pull to Refresh" functionality. Make sure to also set the `refreshing` prop correctly. | Type | Required | | - | - | -| | No | +| function | No | + + +--- + +### `onScrollToIndexFailed` +```javascript +(info: { + index: number, + highestMeasuredFrameIndex: number, + averageItemLength: number, + }) => void +``` + +Used to handle failures when scrolling to an index that has not been measured yet. Recommended action is to either compute your own offset and `scrollTo` it, or scroll as far as possible and then try again after more items have been rendered. + +| Type | Required | +| - | - | +| function | No | --- -### `onEndReachedThreshold` +### `onViewableItemsChanged` + +```javascript +(info: { + viewableItems: array, + changed: array, + }) => void +``` +Called when the viewability of rows changes, as defined by the `viewabilityConfig` prop. | Type | Required | | - | - | -| | No | +| function | No | + + + +--- + + +### `refreshing` + +Set this true while waiting for new data from a refresh. + +| Type | Required | +| - | - | +| boolean | No | + + +--- + + +### `removeClippedSubviews` + +This may improve scroll performance for large lists. + +> Note: +> May have bugs (missing content) in some circumstances - use at your own risk. + +| Type | Required | +| - | - | +| boolean | No | + + +--- + + +### `renderScrollComponent` + +```javascript +(props: object) => element +``` + +Render a custom scroll component, e.g. with a differently styled `RefreshControl`. + +| Type | Required | +| - | - | +| function | No | + + +--- + + +### `viewabilityConfig` + +See `ViewabilityHelper.js` for flow type and further documentation. + +| Type | Required | +| - | - | +| ViewabilityConfig | No | + + + +--- + + +### `viewabilityConfigCallbackPairs` + +List of `ViewabilityConfig`/`onViewableItemsChanged` pairs. A specific `onViewableItemsChanged` will be called when its corresponding `ViewabilityConfig`'s conditions are met. See `ViewabilityHelper.js` for flow type and further documentation. + +| Type | Required | +| - | - | +| array of ViewabilityConfigCallbackPair | No | + + +--- + + + +### `horizontal` + + + +| Type | Required | +| - | - | +| boolean | No | + + + + +--- + +### `initialNumToRender` + +How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions. + +| Type | Required | +| - | - | +| number | No | + + + + +--- + +### `keyExtractor` + +```javascript +(item: object, index: number) => string +``` + +Used to extract a unique key for a given item at the specified index. Key is used for caching and as the react key to track item re-ordering. The default extractor checks `item.key`, then falls back to using the index, like React does. + +| Type | Required | +| - | - | +| function | No | + + + +--- + +### `maxToRenderPerBatch` + +The maximum number of items to render in each incremental render batch. The more rendered at once, the better the fill rate, but responsiveness my suffer because rendering content may interfere with responding to button taps or other interactions. + +| Type | Required | +| - | - | +| number | No | + + +--- + +### `onEndReached` + +```javascript +(info: {distanceFromEnd: number}) => void +``` + +Called once when the scroll position gets within `onEndReachedThreshold` of the rendered content. + +| Type | Required | +| - | - | +| function | No | + +--- + +### `onEndReachedThreshold` + + How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the `onEndReached` callback. Thus a value of 0.5 will trigger `onEndReached` when the end of the content is within half the visible length of the list. + +| Type | Required | +| - | - | +| number | No | + @@ -193,11 +484,11 @@ Some caveats: ### `updateCellsBatchingPeriod` - +Amount of time between low-pri item render batches, e.g. for rendering items quite a ways off screen. Similar fill rate/responsiveness tradeoff as `maxToRenderPerBatch`. | Type | Required | | - | - | -| | No | +| number | No | @@ -206,15 +497,56 @@ Some caveats: ### `windowSize` +Determines the maximum number of items rendered outside of the visible area, in units of visible lengths. So if your list fills the screen, then `windowSize={21}` (the default) will render the visible screen area plus up to 10 screens above and 10 below the viewport. Reducing this number will reduce memory consumption and may improve performance, but will increase the chance that fast scrolling may reveal momentary blank areas of unrendered content. + + +| Type | Required | +| - | - | +| number | No | + + +--- + +### `disableVirtualization` + +**DEPRECATED.** Virtualization provides significant performance and memory optimizations, but fully unmounts react instances that are outside of the render window. You should only need to disable this for debugging purposes. | Type | Required | | - | - | | | No | +--- + + +### `progressViewOffset` + +Set this when offset is needed for the loading indicator to show correctly. +| Type | Required | Platform | +| - | - | - | +| number | No | Android | +## State + +### `first` + + + +| Type | +| - | +| number | + +--- + +### `last` + + +| Type | +| - | +| number | + ## Methods @@ -257,12 +589,11 @@ scrollToOffset(params: object) Scroll to a specific content pixel offset in the list. -Param `offset` expects the offset to scroll to. -In case of `horizontal` is true, the offset is the x-value, -in any other case the offset is the y-value. +**Parameters:** -Param `animated` (`true` by default) defines whether the list -should do an animation while scrolling. +- `offset` expects the offset to scroll to. + In case of `horizontal` is true, the offset is the x-value, in any other case the offset is the y-value. +- `animated` (`true` by default) defines whether the list should do an animation while scrolling. diff --git a/docs/webview.md b/docs/webview.md index 60071707742ba1..bb2b5eea59160e 100644 --- a/docs/webview.md +++ b/docs/webview.md @@ -30,7 +30,7 @@ history and configure various properties for the web content. ### Props -* [ViewPropTypes props...](docs/viewproptypes.html#props) +- [View props...](docs/view-props.html) - [`source`](docs/webview.html#source) - [`automaticallyAdjustContentInsets`](docs/webview.html#automaticallyadjustcontentinsets) - [`injectJavaScript`](docs/webview.html#injectjavascript) @@ -85,8 +85,23 @@ Loads static html or a uri (with optional headers) in the WebView. | Type | Required | | - | - | -| object: {uri: string,method: string,headers: object,body: string}, ,object: {html: string,baseUrl: string}, ,number | No | +| object: {uri: string, method: string, headers: object, body: string},object: {html: string, baseUrl: string}, number | No | +**Keys:** + +An object with either set of keys can be used. Shape: + +- `uri` - The URI to load in the `WebView`. Can be a local or remote file. +- `method` - The HTTP Method to use. Defaults to GET if not specified. On Android, only GET and POST are supported. +- `headers` - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests. +- `body` - The HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied. On Android, this can only be used with POST requests. + +Shape: + +- `html` - A static HTML page to display in the WebView. +- `baseUrl` - The base URL to be used for any relative links in the HTML. + +The packager uses a third type, `number`, internally. @@ -151,14 +166,17 @@ to tap them before they start playing. The default value is `true`. ### `nativeConfig` -Override the native component used to render the WebView. Enables a custom native -WebView which uses the same JavaScript as the original WebView. +Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView. | Type | Required | | - | - | | object: {component: any,props: object,viewManager: object} | No | +**Keys:** +- `component` - The native component used to render the WebView. +- `props` - Set props directly on the native component WebView. Enables custom props which the original WebView doesn't pass through. +- `viewManager` - Set the ViewManager to use for communication with the native side. iOS only. --- @@ -324,7 +342,7 @@ The style to apply to the `WebView`. | Type | Required | | - | - | -| ViewPropTypes.style | No | +| [ViewPropTypes.style](docs/viewproptypes.html#style) | No | @@ -501,7 +519,7 @@ Possible values for `dataDetectorTypes` are: | Type | Required | Platform | | - | - | - | -| enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), ,array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') | No | iOS | +| enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all'), array of enum('phoneNumber', 'link', 'address', 'calendarEvent', 'none', 'all') | No | iOS | @@ -558,7 +576,7 @@ Boolean value that determines whether scrolling is enabled in the ### `extraNativeComponentConfig()` ```javascript -static extraNativeComponentConfig() +WebView.extraNativeComponentConfig() ``` From 57dfb865232e8198118b9f0c47e9c22bd1f763da Mon Sep 17 00:00:00 2001 From: Hector Ramos Date: Wed, 8 Nov 2017 17:50:12 -0800 Subject: [PATCH 2/4] Restore ejected documents --- docs/android-building-from-source.md | 1 + docs/androiduiperformance.md | 7 +++++++ docs/building-for-apple-tv.md | 1 + docs/communication-android.md | 1 + docs/communication-ios.md | 1 + docs/custom-webview-android.md | 1 + docs/custom-webview-ios.md | 1 + docs/headless-js-android.md | 2 +- docs/integration-with-existing-apps.md | 2 +- docs/interactionmanager.md | 13 ++++++++++--- docs/linking-libraries-ios.md | 1 + docs/native-components-android.md | 1 + docs/native-components-ios.md | 1 + docs/native-modules-android.md | 1 + docs/native-modules-ios.md | 1 + docs/nativemethodsmixing.md | 7 +++++++ docs/runningondeviceandroid.md | 7 +++++++ docs/runningondeviceios.md | 7 +++++++ 18 files changed, 51 insertions(+), 5 deletions(-) create mode 100644 docs/androiduiperformance.md create mode 100644 docs/nativemethodsmixing.md create mode 100644 docs/runningondeviceandroid.md create mode 100644 docs/runningondeviceios.md diff --git a/docs/android-building-from-source.md b/docs/android-building-from-source.md index 62b7d37d9f5f31..d88c46cdef5340 100644 --- a/docs/android-building-from-source.md +++ b/docs/android-building-from-source.md @@ -4,6 +4,7 @@ title: Building React Native from source layout: docs category: Guides (Android) permalink: docs/android-building-from-source.html +banner: ejected next: communication-android previous: android-ui-performance --- diff --git a/docs/androiduiperformance.md b/docs/androiduiperformance.md new file mode 100644 index 00000000000000..12eaeb7b7579f5 --- /dev/null +++ b/docs/androiduiperformance.md @@ -0,0 +1,7 @@ +--- +id: android-ui-performance +title: Profiling Android UI Performance +layout: redirect +permalink: docs/android-ui-performance.html +destinationUrl: performance.html +--- \ No newline at end of file diff --git a/docs/building-for-apple-tv.md b/docs/building-for-apple-tv.md index 1692353f2ca1eb..0dc6128cb97c9b 100644 --- a/docs/building-for-apple-tv.md +++ b/docs/building-for-apple-tv.md @@ -4,6 +4,7 @@ title: Building For Apple TV layout: docs category: Guides (iOS) permalink: docs/building-for-apple-tv.html +banner: ejected next: app-extensions previous: communication-ios --- diff --git a/docs/communication-android.md b/docs/communication-android.md index 675d2eba940a1b..133be47408c753 100644 --- a/docs/communication-android.md +++ b/docs/communication-android.md @@ -4,6 +4,7 @@ title: Communication between native and React Native layout: docs category: Guides (Android) permalink: docs/communication-android.html +banner: ejected next: contributing previous: android-building-from-source --- diff --git a/docs/communication-ios.md b/docs/communication-ios.md index 16851169e1b752..7be7fb4a914ea4 100644 --- a/docs/communication-ios.md +++ b/docs/communication-ios.md @@ -4,6 +4,7 @@ title: Communication between native and React Native layout: docs category: Guides (iOS) permalink: docs/communication-ios.html +banner: ejected next: building-for-apple-tv previous: linking-libraries-ios --- diff --git a/docs/custom-webview-android.md b/docs/custom-webview-android.md index 05e0e30a951647..73dbfaf5621052 100644 --- a/docs/custom-webview-android.md +++ b/docs/custom-webview-android.md @@ -4,6 +4,7 @@ title: Custom WebView layout: docs category: Guides (Android) permalink: docs/custom-webview-android.html +banner: ejected next: headless-js-android previous: native-components-android --- diff --git a/docs/custom-webview-ios.md b/docs/custom-webview-ios.md index 8f4de9fdff6b69..8c2d51f80c88fe 100644 --- a/docs/custom-webview-ios.md +++ b/docs/custom-webview-ios.md @@ -4,6 +4,7 @@ title: Custom WebView layout: docs category: Guides (iOS) permalink: docs/custom-webview-ios.html +banner: ejected next: linking-libraries-ios previous: native-components-ios --- diff --git a/docs/headless-js-android.md b/docs/headless-js-android.md index 99aa333484ba6e..4f51a232fceab4 100644 --- a/docs/headless-js-android.md +++ b/docs/headless-js-android.md @@ -89,7 +89,7 @@ Following lines shows part of Android manifest file for registering broadcast re ``` -Broadcast receiver then handles intent that was broadcasted in onReceive function. This is a great place to check whether your app is on foreground or not. If app is not on foreground we can prepare our intent to be started, with no information or additional information bundled using putExta (keep in mind bundle can handle only parcelable values). In the end service is started and wakelock is acquired. +Broadcast receiver then handles intent that was broadcasted in onReceive function. This is a great place to check whether your app is on foreground or not. If app is not on foreground we can prepare our intent to be started, with no information or additional information bundled using `putExtra` (keep in mind bundle can handle only parcelable values). In the end service is started and wakelock is acquired. ```java public class NetworkChangeReceiver extends BroadcastReceiver { diff --git a/docs/integration-with-existing-apps.md b/docs/integration-with-existing-apps.md index 8f708c9b79116a..3aebba0fceb78e 100644 --- a/docs/integration-with-existing-apps.md +++ b/docs/integration-with-existing-apps.md @@ -361,7 +361,7 @@ const styles = StyleSheet.create({ }); // Module name -AppRegistry.registerComponent('MyReactNativeApp', () => RNHighScores); +AppRegistry.registerComponent('RNHighScores', () => RNHighScores); ``` > `RNHighScores` is the name of your module that will be used when you add a view to React Native from within your iOS application. diff --git a/docs/interactionmanager.md b/docs/interactionmanager.md index 2c19e6449ffb1b..e76e85a64bfc82 100644 --- a/docs/interactionmanager.md +++ b/docs/interactionmanager.md @@ -63,12 +63,12 @@ from executing, making apps more responsive. - [`createInteractionHandle`](docs/interactionmanager.html#createinteractionhandle) - [`clearInteractionHandle`](docs/interactionmanager.html#clearinteractionhandle) - [`setDeadline`](docs/interactionmanager.html#setdeadline) +- [`addListener`](docs/interactionmanager.html#addlistener) ### Properties - [`Events`](docs/interactionmanager.html#events) -- [`addListener`](docs/interactionmanager.html#addlistener) @@ -133,14 +133,21 @@ A positive number will use setTimeout to schedule any tasks after the eventLoopRunningTime hits the deadline value, otherwise all tasks will be executed in one setImmediate batch (default). +--- +### `addListener()` +```javascript +InteractionManager.addListener(EventEmitter) +``` -## Properties +## Properties ---- +### `Events` +- `interactionStart` +- `interactionComplete` diff --git a/docs/linking-libraries-ios.md b/docs/linking-libraries-ios.md index 672eadbcfaff10..ad15d09db6e05e 100644 --- a/docs/linking-libraries-ios.md +++ b/docs/linking-libraries-ios.md @@ -4,6 +4,7 @@ title: Linking Libraries layout: docs category: Guides (iOS) permalink: docs/linking-libraries-ios.html +banner: ejected next: running-on-simulator-ios previous: custom-webview-ios --- diff --git a/docs/native-components-android.md b/docs/native-components-android.md index fdee7e4dcf879a..5d0a96e2fc8087 100644 --- a/docs/native-components-android.md +++ b/docs/native-components-android.md @@ -4,6 +4,7 @@ title: Native UI Components layout: docs category: Guides (Android) permalink: docs/native-components-android.html +banner: ejected next: custom-webview-android previous: native-modules-android --- diff --git a/docs/native-components-ios.md b/docs/native-components-ios.md index 85ca430ca72b8a..231f78df6f5197 100644 --- a/docs/native-components-ios.md +++ b/docs/native-components-ios.md @@ -4,6 +4,7 @@ title: Native UI Components layout: docs category: Guides (iOS) permalink: docs/native-components-ios.html +banner: ejected next: custom-webview-ios previous: native-modules-ios --- diff --git a/docs/native-modules-android.md b/docs/native-modules-android.md index 7ff9adacba677e..e4365f187c9f83 100644 --- a/docs/native-modules-android.md +++ b/docs/native-modules-android.md @@ -4,6 +4,7 @@ title: Native Modules layout: docs category: Guides (Android) permalink: docs/native-modules-android.html +banner: ejected next: native-components-android previous: app-extensions --- diff --git a/docs/native-modules-ios.md b/docs/native-modules-ios.md index fa2f760808ab91..de8fe85fe0336d 100644 --- a/docs/native-modules-ios.md +++ b/docs/native-modules-ios.md @@ -4,6 +4,7 @@ title: Native Modules layout: docs category: Guides (iOS) permalink: docs/native-modules-ios.html +banner: ejected next: native-components-ios previous: testing --- diff --git a/docs/nativemethodsmixing.md b/docs/nativemethodsmixing.md new file mode 100644 index 00000000000000..0a4844f272c99f --- /dev/null +++ b/docs/nativemethodsmixing.md @@ -0,0 +1,7 @@ +--- +id: NativeMethodsMixin +title: NativeMethodsMixin +layout: redirect +permalink: docs/nativemethodsmixin.html +destinationUrl: direct-manipulation.html#other-native-methods +--- \ No newline at end of file diff --git a/docs/runningondeviceandroid.md b/docs/runningondeviceandroid.md new file mode 100644 index 00000000000000..df7e48863bf914 --- /dev/null +++ b/docs/runningondeviceandroid.md @@ -0,0 +1,7 @@ +--- +id: running-on-device-android +title: Running On Device +layout: redirect +permalink: docs/running-on-device-android.html +destinationUrl: running-on-device.html +--- \ No newline at end of file diff --git a/docs/runningondeviceios.md b/docs/runningondeviceios.md new file mode 100644 index 00000000000000..7b16664bef65ce --- /dev/null +++ b/docs/runningondeviceios.md @@ -0,0 +1,7 @@ +--- +id: running-on-device-ios +title: Running On Device +layout: redirect +permalink: docs/running-on-device-ios.html +destinationUrl: running-on-device.html +--- \ No newline at end of file From 7d50b7537d411507fbd13db913da4613573ffa7b Mon Sep 17 00:00:00 2001 From: Hector Ramos Date: Thu, 9 Nov 2017 08:23:49 -0800 Subject: [PATCH 3/4] Add content to redirection docs. --- docs/androiduiperformance.md | 3 ++- docs/nativemethodsmixing.md | 13 +++++++------ docs/runningondeviceandroid.md | 3 ++- docs/runningondeviceios.md | 3 ++- 4 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/androiduiperformance.md b/docs/androiduiperformance.md index 12eaeb7b7579f5..d24ffd24b83c21 100644 --- a/docs/androiduiperformance.md +++ b/docs/androiduiperformance.md @@ -4,4 +4,5 @@ title: Profiling Android UI Performance layout: redirect permalink: docs/android-ui-performance.html destinationUrl: performance.html ---- \ No newline at end of file +--- +Redirecting... \ No newline at end of file diff --git a/docs/nativemethodsmixing.md b/docs/nativemethodsmixing.md index 0a4844f272c99f..59e87a89ccd4a5 100644 --- a/docs/nativemethodsmixing.md +++ b/docs/nativemethodsmixing.md @@ -1,7 +1,8 @@ --- -id: NativeMethodsMixin -title: NativeMethodsMixin -layout: redirect -permalink: docs/nativemethodsmixin.html -destinationUrl: direct-manipulation.html#other-native-methods ---- \ No newline at end of file +id: NativeMethodsMixin +title: NativeMethodsMixin +layout: redirect +permalink: docs/nativemethodsmixin.html +destinationUrl: direct-manipulation.html#other-native-methods +--- +Redirecting... \ No newline at end of file diff --git a/docs/runningondeviceandroid.md b/docs/runningondeviceandroid.md index df7e48863bf914..7af98dc23aaa57 100644 --- a/docs/runningondeviceandroid.md +++ b/docs/runningondeviceandroid.md @@ -4,4 +4,5 @@ title: Running On Device layout: redirect permalink: docs/running-on-device-android.html destinationUrl: running-on-device.html ---- \ No newline at end of file +--- +Redirecting... \ No newline at end of file diff --git a/docs/runningondeviceios.md b/docs/runningondeviceios.md index 7b16664bef65ce..3b367bc049a82b 100644 --- a/docs/runningondeviceios.md +++ b/docs/runningondeviceios.md @@ -4,4 +4,5 @@ title: Running On Device layout: redirect permalink: docs/running-on-device-ios.html destinationUrl: running-on-device.html ---- \ No newline at end of file +--- +Redirecting... \ No newline at end of file From 7cd8160ba87b077e59a1910dc68942aec568c38d Mon Sep 17 00:00:00 2001 From: Hector Ramos Date: Thu, 9 Nov 2017 08:40:09 -0800 Subject: [PATCH 4/4] Ensure website deployments happen on master ...never on forked PR builds --- .circleci/config.yml | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 7ee106ab67709b..32902f12fad5e6 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -239,17 +239,22 @@ jobs: command: | cd website npm install --no-package-lock --no-spin --no-progress +# The CIRCLE_PROJECT_USERNAME and CIRCLE_PR_USERNAME checks below +# ensure deploys only happen on projects owned by "facebook", +# never on a forked PR build. - run: name: Build and Deploy Static Website command: | - if [[ $CIRCLE_PROJECT_USERNAME == "facebook" && -z $CI_PULL_REQUEST && -z $CIRCLE_PR_USERNAME ]]; then + if [[ $CIRCLE_PROJECT_USERNAME == "facebook" && -z $CIRCLE_PR_USERNAME ]]; then git config --global user.email "reactjs-bot@users.noreply.github.com" git config --global user.name "Website Deployment Script" echo "machine github.com login reactjs-bot password $GITHUB_TOKEN" > ~/.netrc echo "Deploying website..." cd website && GIT_USER=reactjs-bot npm run gh-pages + elif [[ -n $CIRCLE_PR_USERNAME ]]; then + echo "Skipping website deploy, this is a forked PR build." else - echo "Skipping deploy." + echo "Skipping website deploy." fi # Build JavaScript bundle for Android tests @@ -438,10 +443,12 @@ jobs: - checkout - restore-cache: *restore-cache-analysis - run: *install-node-dependencies +# The CIRCLE_PR_NUMBER checks below ensure +# code analysis only runs on forked PR builds. - run: name: Install Dependencies command: | - if [ -n "$CIRCLE_PULL_REQUEST" ]; then + if [ -n "$CIRCLE_PR_NUMBER" ]; then npm install github@0.2.4 cd danger npm install --no-package-lock --no-spin --no-progress @@ -453,17 +460,17 @@ jobs: - run: name: Analyze Pull Request command: | - if [ -n "$CIRCLE_PULL_REQUEST" ]; then + if [ -n "$CIRCLE_PR_NUMBER" ]; then cd danger && DANGER_GITHUB_API_TOKEN="e622517d9f1136ea8900""07c6373666312cdfaa69" npm run danger else echo "Skipping pull request analysis." fi when: always -# Run eslint +# Run eslint - run: name: Analyze Code command: | - if [ -n "$CIRCLE_PULL_REQUEST" ]; then + if [ -n "$CIRCLE_PR_NUMBER" && -n "$CIRCLE_PROJECT_USERNAME" && -n "$CIRCLE_PROJECT_REPONAME" ]; then cat <(echo eslint; npm run lint --silent -- --format=json; echo flow; npm run flow --silent -- check --json) | GITHUB_TOKEN="af6ef0d15709bc91d""06a6217a5a826a226fb57b7" CI_USER=$CIRCLE_PROJECT_USERNAME CI_REPO=$CIRCLE_PROJECT_REPONAME PULL_REQUEST_NUMBER=$CIRCLE_PR_NUMBER node bots/code-analysis-bot.js else echo "Skipping code analysis."