status-im
/
react-native
mirror of https://github.com/status-im/react-native.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Migrate additional docs to the new format 

Summary:
[DOCS]
Closes https://github.com/facebook/react-native/pull/16874

Differential Revision: D6375515

Pulled By: hramos

fbshipit-source-id: 64359b45a37c7b478919121573ca04dbb1ce6609
This commit is contained in:
Héctor Ramos 2017-11-20 13:07:10 -08:00 committed by Facebook Github Bot
parent f587f8d51d
commit 79e24ede40
19 changed files with 1564 additions and 1634 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
Libraries/ActionSheetIOS/ActionSheetIOS.js
View File

@ -16,34 +16,27 @@ var RCTActionSheetManager = require('NativeModules').ActionSheetManager;
var invariant = require('fbjs/lib/invariant');
var processColor = require('processColor');
/**
* Display action sheets and share sheets on iOS.
*
* See http://facebook.github.io/react-native/docs/actionsheetios.html
*/
var ActionSheetIOS = {
/**
* Display an iOS action sheet. The `options` object must contain one or more
* of:
*
* Display an iOS action sheet.
*
* The `options` object must contain one or more of:
*
* - `options` (array of strings) - a list of button titles (required)
* - `cancelButtonIndex` (int) - index of cancel button in `options`
* - `destructiveButtonIndex` (int) - index of destructive button in `options`
* - `title` (string) - a title to show above the action sheet
* - `message` (string) - a message to show below the title
* - `tintColor` (color) - tint color of the buttons
*
*
* The 'callback' function takes one parameter, the zero-based index
* of the selected item.
*
* Minimal example:
*
* ```
* ActionSheetIOS.showActionSheetWithOptions({
* options: ['Remove', 'Cancel'],
* destructiveButtonIndex: 1,
* cancelButtonIndex: 0,
* },
* (buttonIndex) => {
* if (buttonIndex === 1) { // destructive action }
* });
* ```
*
* See http://facebook.github.io/react-native/docs/actionsheetios.html#showactionsheetwithoptions
*/
showActionSheetWithOptions(options: Object, callback: Function) {
invariant(
@ -68,13 +61,10 @@ var ActionSheetIOS = {
* - `url` (string) - a URL to share
* - `message` (string) - a message to share
* - `subject` (string) - a subject for the message
* - `excludedActivityTypes` (array) - the activities to exclude from the ActionSheet
* - `excludedActivityTypes` (array) - the activities to exclude from
* the ActionSheet
* - `tintColor` (color) - tint color of the buttons
*
* NOTE: if `url` points to a local file, or is a base64-encoded
* uri, the file it points to will be loaded and shared directly.
* In this way, you can share images, videos, PDF files, etc.
*
* The 'failureCallback' function takes one parameter, an error object.
* The only property defined on this object is an optional `stack` property
* of type `string`.
@ -83,6 +73,8 @@ var ActionSheetIOS = {
*
* - a boolean value signifying success or failure
* - a string that, in the case of success, indicates the method of sharing
*
* See http://facebook.github.io/react-native/docs/actionsheetios.html#showshareactionsheetwithoptions
*/
showShareActionSheetWithOptions(
options: Object,

52
Libraries/Alert/Alert.js
View File

@ -30,54 +30,16 @@ type Options = {
/**
* Launches an alert dialog with the specified title and message.
*
* Optionally provide a list of buttons. Tapping any button will fire the
* respective onPress callback and dismiss the alert. By default, the only
* button will be an 'OK' button.
*
* This is an API that works both on iOS and Android and can show static
* alerts. To show an alert that prompts the user to enter some information,
* see `AlertIOS`; entering text in an alert is common on iOS only.
*
* ## iOS
*
* On iOS you can specify any number of buttons. Each button can optionally
* specify a style, which is one of 'default', 'cancel' or 'destructive'.
*
* ## Android
*
* On Android at most three buttons can be specified. Android has a concept
* of a neutral, negative and a positive button:
*
* - If you specify one button, it will be the 'positive' one (such as 'OK')
* - Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
* - Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
*
* By default alerts on Android can be dismissed by tapping outside of the alert
* box. This event can be handled by providing an optional `options` parameter,
* with an `onDismiss` callback property `{ onDismiss: () => {} }`.
*
* Alternatively, the dismissing behavior can be disabled altogether by providing
* an optional `options` parameter with the `cancelable` property set to `false`
* i.e. `{ cancelable: false }`
*
* Example usage:
* ```
* // Works on both iOS and Android
* Alert.alert(
* 'Alert Title',
* 'My Alert Msg',
* [
* {text: 'Ask me later', onPress: () => console.log('Ask me later pressed')},
* {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
* {text: 'OK', onPress: () => console.log('OK Pressed')},
* ],
* { cancelable: false }
* )
* ```
*
* See http://facebook.github.io/react-native/docs/alert.html
*/
class Alert {
/**
* Launches an alert dialog with the specified title and message.
*
* See http://facebook.github.io/react-native/docs/alert.html#alert
*/
static alert(
title: ?string,
message?: ?string,

95
Libraries/Alert/AlertIOS.js
View File

@ -77,60 +77,15 @@ export type ButtonsArray = Array<{
}>;
/**
* @description
* `AlertIOS` provides functionality to create an iOS alert dialog with a
* message or create a prompt for user input.
*
* Creating an iOS alert:
*
* ```
* AlertIOS.alert(
* 'Sync Complete',
* 'All your data are belong to us.'
* );
* ```
*
* Creating an iOS prompt:
*
* ```
* AlertIOS.prompt(
* 'Enter a value',
* null,
* text => console.log("You entered "+text)
* );
* ```
*
* We recommend using the [`Alert.alert`](docs/alert.html) method for
* cross-platform support if you don't need to create iOS-only prompts.
* Use `AlertIOS` to display an alert dialog with a message or to create a prompt for user input on iOS. If you don't need to prompt for user input, we recommend using `Alert.alert() for cross-platform support.
*
* See http://facebook.github.io/react-native/docs/alertios.html
*/
class AlertIOS {
/**
* Create and display a popup alert.
* @static
* @method alert
* @param title The dialog's title. Passing null or '' will hide the title.
* @param message An optional message that appears below
* the dialog's title.
* @param callbackOrButtons 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'.
* @param type Deprecated, do not use.
*
* @example <caption>Example with custom buttons</caption>
*
* AlertIOS.alert(
* 'Update available',
* 'Keep your app up to date to enjoy the latest features',
* [
* {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
* {text: 'Install', onPress: () => console.log('Install Pressed')},
* ],
* );
* See http://facebook.github.io/react-native/docs/alertios.html#alert
*/
static alert(
title: ?string,
@ -148,48 +103,8 @@ class AlertIOS {
/**
* Create and display a prompt to enter some text.
* @static
* @method prompt
* @param title The dialog's title.
* @param message An optional message that appears above the text
* input.
* @param callbackOrButtons 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'.
* @param type This configures the text input. One of 'plain-text',
* 'secure-text' or 'login-password'.
* @param defaultValue The default text in text input.
* @param keyboardType 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'.
*
* @example <caption>Example with custom buttons</caption>
*
* AlertIOS.prompt(
* 'Enter password',
* 'Enter your password to claim your $1.5B in lottery winnings',
* [
* {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
* {text: 'OK', onPress: password => console.log('OK Pressed, password: ' + password)},
* ],
* 'secure-text'
* );
*
* @example <caption>Example with the default button and a custom callback</caption>
*
* AlertIOS.prompt(
* 'Update username',
* null,
* text => console.log("Your username is "+text),
* null,
* 'default'
* );
*
* See http://facebook.github.io/react-native/docs/alertios.html#prompt
*/
static prompt(
title: ?string,

321
Libraries/Animated/src/AnimatedImplementation.js
View File

@ -510,183 +510,33 @@ const event = function(argMapping: Array<?Mapping>, config?: EventConfig): any {
* between inputs and outputs, with configurable transforms in between, and
* simple `start`/`stop` methods to control time-based animation execution.
*
* The simplest workflow for creating an animation is to create an
* `Animated.Value`, hook it up to one or more style attributes of an animated
* component, and then drive updates via animations using `Animated.timing()`:
*
* ```javascript
* Animated.timing( // Animate value over time
* this.state.fadeAnim, // The value to drive
* {
* toValue: 1, // Animate to final value of 1
* }
* ).start(); // Start the animation
* ```
*
* Refer to the [Animations](docs/animations.html#animated-api) guide to see
* additional examples of `Animated` in action.
*
* ## Overview
*
* There are two value types you can use with `Animated`:
*
* - [`Animated.Value()`](docs/animated.html#value) for single values
* - [`Animated.ValueXY()`](docs/animated.html#valuexy) for vectors
*
* `Animated.Value` can bind to style properties or other props, and can be
* interpolated as well. A single `Animated.Value` can drive any number of
* properties.
*
* ### Configuring animations
*
* `Animated` provides three types of animation types. Each animation type
* provides a particular animation curve that controls how your values animate
* from their initial value to the final value:
*
* - [`Animated.decay()`](docs/animated.html#decay) starts with an initial
* velocity and gradually slows to a stop.
* - [`Animated.spring()`](docs/animated.html#spring) provides a simple
* spring physics model.
* - [`Animated.timing()`](docs/animated.html#timing) animates a value over time
* using [easing functions](docs/easing.html).
*
* In most cases, you will be using `timing()`. By default, it uses a symmetric
* easeInOut curve that conveys the gradual acceleration of an object to full
* speed and concludes by gradually decelerating to a stop.
*
* ### Working with animations
*
* Animations are started by calling `start()` on your animation. `start()`
* takes a completion callback that will be called when the animation is done.
* If the animation finished running normally, the completion callback will be
* invoked with `{finished: true}`. If the animation is done because `stop()`
* was called on it before it could finish (e.g. because it was interrupted by a
* gesture or another animation), then it will receive `{finished: false}`.
*
* ### Using the native driver
*
* By using the native driver, we send everything about the animation to native
* before starting the animation, allowing native code to perform the animation
* on the UI thread without having to go through the bridge on every frame.
* Once the animation has started, the JS thread can be blocked without
* affecting the animation.
*
* You can use the native driver by specifying `useNativeDriver: true` in your
* animation configuration. See the
* [Animations](docs/animations.html#using-the-native-driver) guide to learn
* more.
*
* ### Animatable components
*
* Only animatable components can be animated. These special components do the
* magic of binding the animated values to the properties, and do targeted
* native updates to avoid the cost of the react render and reconciliation
* process on every frame. They also handle cleanup on unmount so they are safe
* by default.
*
* - [`createAnimatedComponent()`](docs/animated.html#createanimatedcomponent)
* can be used to make a component animatable.
*
* `Animated` exports the following animatable components using the above
* wrapper:
*
* - `Animated.Image`
* - `Animated.ScrollView`
* - `Animated.Text`
* - `Animated.View`
*
* ### Composing animations
*
* Animations can also be combined in complex ways using composition functions:
*
* - [`Animated.delay()`](docs/animated.html#delay) starts an animation after
* a given delay.
* - [`Animated.parallel()`](docs/animated.html#parallel) starts a number of
* animations at the same time.
* - [`Animated.sequence()`](docs/animated.html#sequence) starts the animations
* in order, waiting for each to complete before starting the next.
* - [`Animated.stagger()`](docs/animated.html#stagger) starts animations in
* order and in parallel, but with successive delays.
*
* Animations can also be chained together simply by setting the `toValue` of
* one animation to be another `Animated.Value`. See
* [Tracking dynamic values](docs/animations.html#tracking-dynamic-values) in
* the Animations guide.
*
* By default, if one animation is stopped or interrupted, then all other
* animations in the group are also stopped.
*
* ### Combining animated values
*
* You can combine two animated values via addition, multiplication, division,
* or modulo to make a new animated value:
*
* - [`Animated.add()`](docs/animated.html#add)
* - [`Animated.divide()`](docs/animated.html#divide)
* - [`Animated.modulo()`](docs/animated.html#modulo)
* - [`Animated.multiply()`](docs/animated.html#multiply)
*
* ### Interpolation
*
* The `interpolate()` function allows input ranges to map to different output
* ranges. By default, it will extrapolate the curve beyond the ranges given,
* but you can also have it clamp the output value. It uses lineal interpolation
* by default but also supports easing functions.
*
* - [`interpolate()`](docs/animated.html#interpolate)
*
* Read more about interpolation in the
* [Animation](docs/animations.html#interpolation) guide.
*
* ### Handling gestures and other events
*
* Gestures, like panning or scrolling, and other events can map directly to
* animated values using `Animated.event()`. This is done with a structured map
* syntax so that values can be extracted from complex event objects. The first
* level is an array to allow mapping across multiple args, and that array
* contains nested objects.
*
* - [`Animated.event()`](docs/animated.html#event)
*
* For example, when working with horizontal scrolling gestures, you would do
* the following in order to map `event.nativeEvent.contentOffset.x` to
* `scrollX` (an `Animated.Value`):
*
* ```javascript
* onScroll={Animated.event(
* // scrollX = e.nativeEvent.contentOffset.x
* [{ nativeEvent: {
* contentOffset: {
* x: scrollX
* }
* }
* }]
* )}
* ```
*
* See http://facebook.github.io/react-native/docs/animated.html
*/
module.exports = {
/**
* Standard value class for driving animations. Typically initialized with
* `new Animated.Value(0);`
*
* See also [`AnimatedValue`](docs/animated.html#animatedvalue).
* See http://facebook.github.io/react-native/docs/animated.html#value
*/
Value: AnimatedValue,
/**
* 2D value class for driving 2D animations, such as pan gestures.
*
* See also [`AnimatedValueXY`](docs/animated.html#animatedvaluexy).
* See http://facebook.github.io/react-native/docs/animated.html#valuexy
*/
ValueXY: AnimatedValueXY,
/**
* exported to use the Interpolation type in flow
*
* See also [`AnimatedInterpolation`](docs/animated.html#animatedinterpolation).
* Exported to use the Interpolation type in flow.
*
* See http://facebook.github.io/react-native/docs/animated.html#interpolation
*/
Interpolation: AnimatedInterpolation,
/**
* Exported for ease of type checking. All animated values derive from this class.
* Exported for ease of type checking. All animated values derive from this
* class.
*
* See http://facebook.github.io/react-native/docs/animated.html#node
*/
Node: AnimatedNode,
@ -694,185 +544,130 @@ module.exports = {
* Animates a value from an initial velocity to zero based on a decay
* coefficient.
*
* Config is an object that may have the following options:
*
* - `velocity`: Initial velocity. Required.
* - `deceleration`: Rate of decay. Default 0.997.
* - `isInteraction`: Whether or not this animation creates an "interaction handle" on the
* `InteractionManager`. Default true.
* - `useNativeDriver`: Uses the native driver when true. Default false.
* See http://facebook.github.io/react-native/docs/animated.html#decay
*/
decay,
/**
* Animates a value along a timed easing curve. The
* [`Easing`](docs/easing.html) module has tons of predefined curves, or you
* can use your own function.
* Animates a value along a timed easing curve. The Easing module has tons of
* predefined curves, or you can use your own function.
*
* Config is an object that may have the following options:
*
* - `duration`: Length of animation (milliseconds). Default 500.
* - `easing`: Easing function to define curve.
* Default is `Easing.inOut(Easing.ease)`.
* - `delay`: Start the animation after delay (milliseconds). Default 0.
* - `isInteraction`: Whether or not this animation creates an "interaction handle" on the
* `InteractionManager`. Default true.
* - `useNativeDriver`: Uses the native driver when true. Default false.
* See http://facebook.github.io/react-native/docs/animated.html#timing
*/
timing,
/**
* Animates a value according to an analytical spring model based on
* [damped harmonic oscillation](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator).
* Tracks velocity state to create fluid motions as the `toValue` updates, and
* can be chained together.
*
* Config is an object that may have the following options.
*
* Note that you can only define one of bounciness/speed, tension/friction, or
* stiffness/damping/mass, but not more than one:
*
* The friction/tension or bounciness/speed options match the spring model in
* [Facebook Pop](https://github.com/facebook/pop), [Rebound](http://facebook.github.io/rebound/),
* and [Origami](http://origami.design/).
*
* - `friction`: Controls "bounciness"/overshoot. Default 7.
* - `tension`: Controls speed. Default 40.
* - `speed`: Controls speed of the animation. Default 12.
* - `bounciness`: Controls bounciness. Default 8.
*
* Specifying stiffness/damping/mass as parameters makes `Animated.spring` use an
* analytical spring model based on the motion equations of a [damped harmonic
* oscillator](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator).
* This behavior is slightly more precise and faithful to the physics behind
* spring dynamics, and closely mimics the implementation in iOS's
* CASpringAnimation primitive.
*
* - `stiffness`: The spring stiffness coefficient. Default 100.
* - `damping`: Defines how the spring’s motion should be damped due to the forces of friction.
* Default 10.
* - `mass`: The mass of the object attached to the end of the spring. Default 1.
*
* Other configuration options are as follows:
*
* - `velocity`: The initial velocity of the object attached to the spring. Default 0 (object
* is at rest).
* - `overshootClamping`: Boolean indiciating whether the spring should be clamped and not
* bounce. Default false.
* - `restDisplacementThreshold`: The threshold of displacement from rest below which the
* spring should be considered at rest. Default 0.001.
* - `restSpeedThreshold`: The speed at which the spring should be considered at rest in pixels
* per second. Default 0.001.
* - `delay`: Start the animation after delay (milliseconds). Default 0.
* - `isInteraction`: Whether or not this animation creates an "interaction handle" on the
* `InteractionManager`. Default true.
* - `useNativeDriver`: Uses the native driver when true. Default false.
* damped harmonic oscillation.
*
* See http://facebook.github.io/react-native/docs/animated.html#spring
*/
spring,
/**
* Creates a new Animated value composed from two Animated values added
* together.
*
* See http://facebook.github.io/react-native/docs/animated.html#add
*/
add,
/**
* Creates a new Animated value composed by dividing the first Animated value
* by the second Animated value.
*
* See http://facebook.github.io/react-native/docs/animated.html#divide
*/
divide,
/**
* Creates a new Animated value composed from two Animated values multiplied
* together.
*
* See http://facebook.github.io/react-native/docs/animated.html#multiply
*/
multiply,
/**
* Creates a new Animated value that is the (non-negative) modulo of the
* provided Animated value
* provided Animated value.
*
* See http://facebook.github.io/react-native/docs/animated.html#modulo
*/
modulo,
/**
* Create a new Animated value that is limited between 2 values. It uses the
* difference between the last value so even if the value is far from the bounds
* it will start changing when the value starts getting closer again.
* (`value = clamp(value + diff, min, max)`).
*
* This is useful with scroll events, for example, to show the navbar when
* scrolling up and to hide it when scrolling down.
* difference between the last value so even if the value is far from the
* bounds it will start changing when the value starts getting closer again.
*
* See http://facebook.github.io/react-native/docs/animated.html#diffclamp
*/
diffClamp,
/**
* Starts an animation after the given delay.
*
* See http://facebook.github.io/react-native/docs/animated.html#delay
*/
delay,
/**
* Starts an array of animations in order, waiting for each to complete
* before starting the next. If the current running animation is stopped, no
* before starting the next. If the current running animation is stopped, no
* following animations will be started.
*
* See http://facebook.github.io/react-native/docs/animated.html#sequence
*/
sequence,
/**
* Starts an array of animations all at the same time. By default, if one
* of the animations is stopped, they will all be stopped. You can override
* Starts an array of animations all at the same time. By default, if one
* of the animations is stopped, they will all be stopped. You can override
* this with the `stopTogether` flag.
*
* See http://facebook.github.io/react-native/docs/animated.html#parallel
*/
parallel,
/**
* Array of animations may run in parallel (overlap), but are started in
* sequence with successive delays. Nice for doing trailing effects.
*
* See http://facebook.github.io/react-native/docs/animated.html#stagger
*/
stagger,
/**
* Loops a given animation continuously, so that each time it reaches the
* end, it resets and begins again from the start. Can specify number of
* times to loop using the key `iterations` in the config. Will loop without
* blocking the UI thread if the child animation is set to `useNativeDriver: true`.
* In addition, loops can prevent `VirtualizedList`-based components from rendering
* more rows while the animation is running. You can pass `isInteraction: false` in the
* child animation config to fix this.
* Loops a given animation continuously, so that each time it reaches the
* end, it resets and begins again from the start.
*
* See http://facebook.github.io/react-native/docs/animated.html#loop
*/
loop,
/**
* Takes an array of mappings and extracts values from each arg accordingly,
* then calls `setValue` on the mapped outputs. e.g.
*
*```javascript
* onScroll={Animated.event(
* [{nativeEvent: {contentOffset: {x: this._scrollX}}}],
* {listener: (event) => console.log(event)}, // Optional async listener
* )}
* ...
* onPanResponderMove: Animated.event([
* null, // raw event arg ignored
* {dx: this._panX}, // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
* ]),
*```
*
* Config is an object that may have the following options:
*
* - `listener`: Optional async listener.
* - `useNativeDriver`: Uses the native driver when true. Default false.
* then calls `setValue` on the mapped outputs.
*
* See http://facebook.github.io/react-native/docs/animated.html#event
*/
event,
/**
* Make any React component Animatable. Used to create `Animated.View`, etc.
*
* See http://facebook.github.io/react-native/docs/animated.html#createanimatedcomponent
*/
createAnimatedComponent,
/**
* Imperative API to attach an animated value to an event on a view. Prefer using
* `Animated.event` with `useNativeDrive: true` if possible.
* Imperative API to attach an animated value to an event on a view. Prefer
* using `Animated.event` with `useNativeDrive: true` if possible.
*
* See http://facebook.github.io/react-native/docs/animated.html#attachnativeevent
*/
attachNativeEvent,
/**
* Advanced imperative API for snooping on animated events that are passed in through props. Use
* values directly where possible.
* Advanced imperative API for snooping on animated events that are passed in
* through props. Use values directly where possible.
*
* See http://facebook.github.io/react-native/docs/animated.html#forkevent
*/
forkEvent,
unforkEvent,

35
Libraries/Animated/src/nodes/AnimatedValue.js
View File

@ -68,6 +68,8 @@ function _flush(rootNode: AnimatedValue): void {
* multiple properties in a synchronized fashion, but can only be driven by one
* mechanism at a time. Using a new mechanism (e.g. starting a new animation,
* or calling `setValue`) will stop any previous ones.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html
*/
class AnimatedValue extends AnimatedWithChildren {
_value: number;
@ -106,6 +108,8 @@ class AnimatedValue extends AnimatedWithChildren {
/**
* Directly set the value. This will stop any animations running on the value
* and update all the bound properties.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#setvalue
*/
setValue(value: number): void {
if (this._animation) {
@ -125,6 +129,8 @@ class AnimatedValue extends AnimatedWithChildren {
* Sets an offset that is applied on top of whatever value is set, whether via
* `setValue`, an animation, or `Animated.event`. Useful for compensating
* things like the start of a pan gesture.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#setoffset
*/
setOffset(offset: number): void {
this._offset = offset;
@ -136,6 +142,8 @@ class AnimatedValue extends AnimatedWithChildren {
/**
* Merges the offset value into the base value and resets the offset to zero.
* The final output of the value is unchanged.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#flattenoffset
*/
flattenOffset(): void {
this._value += this._offset;
@ -148,6 +156,8 @@ class AnimatedValue extends AnimatedWithChildren {
/**
* Sets the offset value to the base value, and resets the base value to zero.
* The final output of the value is unchanged.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#extractoffset
*/
extractOffset(): void {
this._offset += this._value;
@ -161,6 +171,8 @@ class AnimatedValue extends AnimatedWithChildren {
* Adds an asynchronous listener to the value so you can observe updates from
* animations. This is useful because there is no way to
* synchronously read the value because it might be driven natively.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#addlistener
*/
addListener(callback: ValueListenerCallback): string {
const id = String(_uniqueId++);
@ -171,6 +183,12 @@ class AnimatedValue extends AnimatedWithChildren {
return id;
}
/**
* Unregister a listener. The `id` param shall match the identifier
* previously returned by `addListener()`.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#removelistener
*/
removeListener(id: string): void {
delete this._listeners[id];
if (this.__isNative && Object.keys(this._listeners).length === 0) {
@ -178,6 +196,11 @@ class AnimatedValue extends AnimatedWithChildren {
}
}
/**
* Remove all registered listeners.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#removealllisteners
*/
removeAllListeners(): void {
this._listeners = {};
if (this.__isNative) {
@ -213,9 +236,11 @@ class AnimatedValue extends AnimatedWithChildren {
}
/**
* Stops any running animation or tracking. `callback` is invoked with the
* Stops any running animation or tracking. `callback` is invoked with the
* final value after stopping the animation, which is useful for updating
* state to match the animation position with layout.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#stopanimation
*/
stopAnimation(callback?: ?(value: number) => void): void {
this.stopTracking();
@ -225,8 +250,10 @@ class AnimatedValue extends AnimatedWithChildren {
}
/**
* Stops any animation and resets the value to its original
*/
* Stops any animation and resets the value to its original.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#resetanimation
*/
resetAnimation(callback?: ?(value: number) => void): void {
this.stopAnimation(callback);
this._value = this._startingValue;
@ -243,6 +270,8 @@ class AnimatedValue extends AnimatedWithChildren {
/**
* Typically only used internally, but could be used by a custom Animation
* class.
*
* See http://facebook.github.io/react-native/docs/animatedvalue.html#animate
*/
animate(animation: Animation, callback: ?EndCallback): void {
let handle = null;

117
Libraries/Animated/src/nodes/AnimatedValueXY.js
View File

@ -22,44 +22,10 @@ type ValueXYListenerCallback = (value: {x: number, y: number}) => void;
let _uniqueId = 1;
/**
* 2D Value for driving 2D animations, such as pan gestures. Almost identical
* API to normal `Animated.Value`, but multiplexed. Contains two regular
* `Animated.Value`s under the hood.
*
* #### Example
*
*```javascript
* class DraggableView extends React.Component {
* constructor(props) {
* super(props);
* this.state = {
* pan: new Animated.ValueXY(), // inits to zero
* };
* this.state.panResponder = PanResponder.create({
* onStartShouldSetPanResponder: () => true,
* onPanResponderMove: Animated.event([null, {
* dx: this.state.pan.x, // x,y are Animated.Value
* dy: this.state.pan.y,
* }]),
* onPanResponderRelease: () => {
* Animated.spring(
* this.state.pan, // Auto-multiplexed
* {toValue: {x: 0, y: 0}} // Back to zero
* ).start();
* },
* });
* }
* render() {
* return (
* <Animated.View
* {...this.state.panResponder.panHandlers}
* style={this.state.pan.getLayout()}>
* {this.props.children}
* </Animated.View>
* );
* }
* }
*```
* 2D Value for driving 2D animations, such as pan gestures. Almost identical
* API to normal `Animated.Value`, but multiplexed.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html
*/
class AnimatedValueXY extends AnimatedWithChildren {
x: AnimatedValue;
@ -86,21 +52,46 @@ class AnimatedValueXY extends AnimatedWithChildren {
this._listeners = {};
}
/**
* Directly set the value. This will stop any animations running on the value
* and update all the bound properties.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#setvalue
*/
setValue(value: {x: number, y: number}) {
this.x.setValue(value.x);
this.y.setValue(value.y);
}
/**
* Sets an offset that is applied on top of whatever value is set, whether
* via `setValue`, an animation, or `Animated.event`. Useful for compensating
* things like the start of a pan gesture.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#setoffset
*/
setOffset(offset: {x: number, y: number}) {
this.x.setOffset(offset.x);
this.y.setOffset(offset.y);
}
/**
* Merges the offset value into the base value and resets the offset to zero.
* The final output of the value is unchanged.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#flattenoffset
*/
flattenOffset(): void {
this.x.flattenOffset();
this.y.flattenOffset();
}
/**
* Sets the offset value to the base value, and resets the base value to
* zero. The final output of the value is unchanged.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#extractoffset
*/
extractOffset(): void {
this.x.extractOffset();
this.y.extractOffset();
@ -113,18 +104,39 @@ class AnimatedValueXY extends AnimatedWithChildren {
};
}
/**
* Stops any animation and resets the value to its original.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#resetanimation
*/
resetAnimation(callback?: (value: {x: number, y: number}) => void): void {
this.x.resetAnimation();
this.y.resetAnimation();
callback && callback(this.__getValue());
}
/**
* Stops any running animation or tracking. `callback` is invoked with the
* final value after stopping the animation, which is useful for updating
* state to match the animation position with layout.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#stopanimation
*/
stopAnimation(callback?: (value: {x: number, y: number}) => void): void {
this.x.stopAnimation();
this.y.stopAnimation();
callback && callback(this.__getValue());
}
/**
* Adds an asynchronous listener to the value so you can observe updates from
* animations. This is useful because there is no way to synchronously read
* the value because it might be driven natively.
*
* Returns a string that serves as an identifier for the listener.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#addlistener
*/
addListener(callback: ValueXYListenerCallback): string {
const id = String(_uniqueId++);
const jointCallback = ({value: number}) => {
@ -137,12 +149,23 @@ class AnimatedValueXY extends AnimatedWithChildren {
return id;
}
/**
* Unregister a listener. The `id` param shall match the identifier
* previously returned by `addListener()`.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#removelistener
*/
removeListener(id: string): void {
this.x.removeListener(this._listeners[id].x);
this.y.removeListener(this._listeners[id].y);
delete this._listeners[id];
}
/**
* Remove all registered listeners.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#removealllisteners
*/
removeAllListeners(): void {
this.x.removeAllListeners();
this.y.removeAllListeners();
@ -150,11 +173,9 @@ class AnimatedValueXY extends AnimatedWithChildren {
}
/**
* Converts `{x, y}` into `{left, top}` for use in style, e.g.
*
*```javascript
* style={this.state.anim.getLayout()}
*```
* Converts `{x, y}` into `{left, top}` for use in style.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#getlayout
*/
getLayout(): {[key: string]: AnimatedValue} {
return {
@ -164,13 +185,9 @@ class AnimatedValueXY extends AnimatedWithChildren {
}
/**
* Converts `{x, y}` into a useable translation transform, e.g.
*
*```javascript
* style={{
* transform: this.state.anim.getTranslateTransform()
* }}
*```
* Converts `{x, y}` into a useable translation transform.
*
* See http://facebook.github.io/react-native/docs/animatedvaluexy.html#gettranslatetransform
*/
getTranslateTransform(): Array<{[key: string]: AnimatedValue}> {
return [{translateX: this.x}, {translateY: this.y}];

100
Libraries/AppState/AppState.js
View File

@ -23,66 +23,8 @@ const invariant = require('fbjs/lib/invariant');
* `AppState` can tell you if the app is in the foreground or background,
* and notify you when the state changes.
*
* AppState is frequently used to determine the intent and proper behavior when
* 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
*
* 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.
*
* ```
* import React, {Component} from 'react'
* import {AppState, Text} from 'react-native'
*
* class AppStateExample extends Component {
*
* state = {
* appState: AppState.currentState
* }
*
* componentDidMount() {
* AppState.addEventListener('change', this._handleAppStateChange);
* }
*
* componentWillUnmount() {
* AppState.removeEventListener('change', this._handleAppStateChange);
* }
*
* _handleAppStateChange = (nextAppState) => {
* if (this.state.appState.match(/inactive|background/) && nextAppState === 'active') {
* console.log('App has come to the foreground!')
* }
* this.setState({appState: nextAppState});
* }
*
* render() {
* return (
* <Text>Current state is: {this.state.appState}</Text>
* );
* }
*
* }
* ```
*
* 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.
* See http://facebook.github.io/react-native/docs/appstate.html
*/
class AppState extends NativeEventEmitter {
_eventHandlers: Object;
@ -104,10 +46,10 @@ class AppState extends NativeEventEmitter {
let eventUpdated = false;
// TODO: this is a terrible solution - in order to ensure `currentState` prop
// is up to date, we have to register an observer that updates it whenever
// the state changes, even if nobody cares. We should just deprecate the
// `currentState` property and get rid of this.
// TODO: this is a terrible solution - in order to ensure `currentState`
// prop is up to date, we have to register an observer that updates it
// whenever the state changes, even if nobody cares. We should just
// deprecate the `currentState` property and get rid of this.
this.addListener(
'appStateDidChange',
(appStateData) => {
@ -117,8 +59,8 @@ class AppState extends NativeEventEmitter {
);
// TODO: see above - this request just populates the value of `currentState`
// when the module is first initialized. Would be better to get rid of the prop
// and expose `getCurrentAppState` method directly.
// when the module is first initialized. Would be better to get rid of the
// prop and expose `getCurrentAppState` method directly.
RCTAppState.getCurrentAppState(
(appStateData) => {
if (!eventUpdated) {
@ -129,15 +71,16 @@ class AppState extends NativeEventEmitter {
);
}
/**
// 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).
/**
* 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).
* and providing the handler.
*
* See http://facebook.github.io/react-native/docs/appstate.html#addeventlistener
*/
addEventListener(
type: string,
@ -163,7 +106,9 @@ class AppState extends NativeEventEmitter {
}
/**
* Remove a handler by passing the `change` event type and the handler
* Remove a handler by passing the `change` event type and the handler.
*
* See http://facebook.github.io/react-native/docs/appstate.html#removeeventlistener
*/
removeEventListener(
type: string,
@ -200,9 +145,10 @@ if (__DEV__ && !RCTAppState) {
}
}
// This module depends on the native `RCTAppState` module. If you don't include it,
// `AppState.isAvailable` will return `false`, and any method calls will throw.
// We reassign the class variable to keep the autodoc generator happy.
// This module depends on the native `RCTAppState` module. If you don't
// include it, `AppState.isAvailable` will return `false`, and any method
// calls will throw. We reassign the class variable to keep the autodoc
// generator happy.
AppState = new MissingNativeAppStateShim();
} else {
AppState = new AppState();

52
Libraries/ReactNative/AppRegistry.js
View File

@ -58,30 +58,9 @@ let componentProviderInstrumentationHook: ComponentProviderInstrumentationHook =
let wrapperComponentProvider: ?WrapperComponentProvider;
/**
* <div class="banner-crna-ejected">
* <h3>Project with Native Code Required</h3>
* <p>
* This API only works in projects made with <code>react-native init</code>
* or in those made with Create React Native App which have since ejected. For
* more information about ejecting, please see
* the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
* the Create React Native App repository.
* </p>
* </div>
*
* `AppRegistry` is the JS entry point to running all React Native apps. App
* root components should register themselves with
* `AppRegistry.registerComponent`, then the native system can load the bundle
* for the app and then actually run the app when it's ready by invoking
* `AppRegistry.runApplication`.
*
* To "stop" an application when a view should be destroyed, call
* `AppRegistry.unmountApplicationComponentAtRootTag` with the tag that was
* passed into `runApplication`. These should always be used as a pair.
*
* `AppRegistry` should be `require`d early in the `require` sequence to make
* sure the JS execution environment is setup before other modules are
* `require`d.
* `AppRegistry` is the JavaScript entry point to running all React Native apps.
*
* See http://facebook.github.io/react-native/docs/appregistry.html
*/
const AppRegistry = {
setWrapperComponentProvider(provider: WrapperComponentProvider) {
@ -108,6 +87,11 @@ const AppRegistry = {
});
},
/**
* Registers an app's root component.
*
* See http://facebook.github.io/react-native/docs/appregistry.html#registercomponent
*/
registerComponent(
appKey: string,
componentProvider: ComponentProvider,
@ -169,6 +153,11 @@ const AppRegistry = {
componentProviderInstrumentationHook = hook;
},
/**
* Loads the JavaScript bundle and runs the app.
*
* See http://facebook.github.io/react-native/docs/appregistry.html#runapplication
*/
runApplication(appKey: string, appParameters: any): void {
const msg =
'Running application "' +
@ -207,16 +196,19 @@ const AppRegistry = {
runnables[appKey].run(appParameters);
},
/**
* Stops an application when a view should be destroyed.
*
* See http://facebook.github.io/react-native/docs/appregistry.html#unmountapplicationcomponentatroottag
*/
unmountApplicationComponentAtRootTag(rootTag: number): void {
ReactNative.unmountComponentAtNodeAndRemoveContainer(rootTag);
},
/**
* 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.
*
* See http://facebook.github.io/react-native/docs/appregistry.html#registerheadlesstask
*/
registerHeadlessTask(taskKey: string, task: TaskProvider): void {
if (tasks.has(taskKey)) {
@ -230,9 +222,7 @@ const AppRegistry = {
/**
* 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
* See http://facebook.github.io/react-native/docs/appregistry.html#startheadlesstask
*/
startHeadlessTask(taskId: number, taskKey: string, data: any): void {
const taskProvider = tasks.get(taskKey);

230
Libraries/Storage/AsyncStorage.js
View File

@ -21,45 +21,11 @@ const RCTAsyncStorage = NativeModules.AsyncRocksDBStorage ||
NativeModules.AsyncLocalStorage;
/**
* @class
* @description
* `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.
*
* 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.
*
* Persisting data:
* ```
* try {
* await AsyncStorage.setItem('@MySuperStore:key', 'I like to save it.');
* } catch (error) {
* // Error saving data
* }
* ```
*
* Fetching data:
* ```
* try {
* const value = await AsyncStorage.getItem('@MySuperStore:key');
* if (value !== null){
* // We have data!!
* console.log(value);
* }
* } catch (error) {
* // Error retrieving data
* }
* ```
* `AsyncStorage` is a simple, unencrypted, asynchronous, persistent, key-value
* storage system that is global to the app. It should be used instead of
* LocalStorage.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html
*/
var AsyncStorage = {
_getRequests: ([]: Array<any>),
@ -68,11 +34,8 @@ var AsyncStorage = {
/**
* Fetches an item for a `key` and invokes a callback upon completion.
* Returns a `Promise` object.
* @param key Key of the item to fetch.
* @param callback Function that will be called with a result if found or
* any error.
* @returns A `Promise` object.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#getitem
*/
getItem: function(
key: string,
@ -95,11 +58,8 @@ var AsyncStorage = {
/**
* Sets the value for a `key` and invokes a callback upon completion.
* Returns a `Promise` object.
* @param key Key of the item to set.
* @param value Value to set for the `key`.
* @param callback Function that will be called with any error.
* @returns A `Promise` object.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#setitem
*/
setItem: function(
key: string,
@ -121,10 +81,8 @@ var AsyncStorage = {
/**
* Removes an item for a `key` and invokes a callback upon completion.
* Returns a `Promise` object.
* @param key Key of the item to remove.
* @param callback Function that will be called with any error.
* @returns A `Promise` object.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#removeitem
*/
removeItem: function(
key: string,
@ -145,38 +103,11 @@ var AsyncStorage = {
/**
* Merges an existing `key` value with an input value, assuming both values
* are stringified JSON. Returns a `Promise` object.
* are stringified JSON.
*
* **NOTE:** This is not supported by all native implementations.
*
* @param key Key of the item to modify.
* @param value New value to merge for the `key`.
* @param callback Function that will be called with any error.
* @returns A `Promise` object.
*
* @example <caption>Example</caption>
* let UID123_object = {
* 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}
* };
*
* AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => {
* AsyncStorage.mergeItem('UID123', JSON.stringify(UID123_delta), () => {
* AsyncStorage.getItem('UID123', (err, result) => {
* console.log(result);
* });
* });
* });
*
* // Console log result:
* // => {'name':'Chris','age':31,'traits':
* // {'shoe_size':10,'hair':'brown','eyes':'blue'}}
* See http://facebook.github.io/react-native/docs/asyncstorage.html#mergeitem
*/
mergeItem: function(
key: string,
@ -197,11 +128,11 @@ var AsyncStorage = {
},
/**
* Erases *all* `AsyncStorage` for all clients, libraries, etc. You probably
* 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.
* @param callback Function that will be called with any error.
* @returns A `Promise` object.
* your app's keys.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#clear
*/
clear: function(callback?: ?(error: ?Error) => void): Promise {
return new Promise((resolve, reject) => {
@ -218,11 +149,8 @@ var AsyncStorage = {
/**
* Gets *all* keys known to your app; for all callers, libraries, etc.
* Returns a `Promise` object.
* @param callback Function that will be called the keys found and any error.
* @returns A `Promise` object.
*
* Example: see the `multiGet` example.
* See http://facebook.github.io/react-native/docs/asyncstorage.html#getallkeys
*/
getAllKeys: function(callback?: ?(error: ?Error, keys: ?Array<string>) => void): Promise {
return new Promise((resolve, reject) => {
@ -247,7 +175,11 @@ var AsyncStorage = {
* indicate which key caused the error.
*/
/** Flushes any pending requests using a single batch call to get the data. */
/**
* Flushes any pending requests using a single batch call to get the data.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#flushgetrequests
* */
flushGetRequests: function(): void {
const getRequests = this._getRequests;
const getKeys = this._getKeys;
@ -278,30 +210,9 @@ var AsyncStorage = {
/**
* 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']])
* ```
*
* The method returns a `Promise` object.
*
* @param keys Array of key for the items to get.
* @param callback Function that will be called with a key-value array of
* the results, plus an array of any key-specific errors found.
* @returns A `Promise` object.
*
* @example <caption>Example</caption>
*
* AsyncStorage.getAllKeys((err, keys) => {
* AsyncStorage.multiGet(keys, (err, stores) => {
* stores.map((result, i, store) => {
* // get at each store's key/value so you can work with it
* let key = store[i][0];
* let value = store[i][1];
* });
* });
* });
* key-value pairs found.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#multiget
*/
multiGet: function(
keys: Array<string>,
@ -341,19 +252,9 @@ var AsyncStorage = {
/**
* Use this as a batch operation for storing multiple key-value pairs. When
* the operation completes you'll get a single callback with any errors:
* the operation completes you'll get a single callback with any errors.
*
* ```
* multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
* ```
*
* The method returns a `Promise` object.
*
* @param keyValuePairs Array of key-value array for the items to set.
* @param callback Function that will be called with an array of any
* key-specific errors found.
* @returns A `Promise` object.
* Example: see the `multiMerge` example.
* See http://facebook.github.io/react-native/docs/asyncstorage.html#multiset
*/
multiSet: function(
keyValuePairs: Array<Array<string>>,
@ -373,20 +274,9 @@ var AsyncStorage = {
},
/**
* Call this to batch the deletion of all keys in the `keys` array. Returns
* a `Promise` object.
*
* @param keys Array of key for the items to delete.
* @param callback Function that will be called an array of any key-specific
* errors found.
* @returns A `Promise` object.
*
* @example <caption>Example</caption>
* let keys = ['k1', 'k2'];
* AsyncStorage.multiRemove(keys, (err) => {
* // keys k1 & k2 removed, if they existed
* // do most stuff after removal (if you want)
* });
* Call this to batch the deletion of all keys in the `keys` array.
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#multiremove
*/
multiRemove: function(
keys: Array<string>,
@ -407,61 +297,11 @@ var AsyncStorage = {
/**
* Batch operation to merge in existing and new values for a given set of
* keys. This assumes that the values are stringified JSON. Returns a
* `Promise` object.
*
* keys. This assumes that the values are stringified JSON.
*
* **NOTE**: This is not supported by all native implementations.
*
* @param keyValuePairs Array of key-value array for the items to merge.
* @param callback Function that will be called with an array of any
* key-specific errors found.
* @returns A `Promise` object.
*
* @example <caption>Example</caption>
* // first user, initial values
* let UID234_object = {
* name: 'Chris',
* age: 30,
* traits: {hair: 'brown', eyes: 'brown'},
* };
*
* // first user, delta values
* let UID234_delta = {
* age: 31,
* traits: {eyes: 'blue', shoe_size: 10},
* };
*
* // second user, initial values
* let UID345_object = {
* name: 'Marge',
* age: 25,
* traits: {hair: 'blonde', eyes: 'blue'},
* };
*
* // second user, delta values
* let UID345_delta = {
* age: 26,
* traits: {eyes: 'green', shoe_size: 6},
* };
*
* let multi_set_pairs = [['UID234', JSON.stringify(UID234_object)], ['UID345', JSON.stringify(UID345_object)]]
* let multi_merge_pairs = [['UID234', JSON.stringify(UID234_delta)], ['UID345', JSON.stringify(UID345_delta)]]
*
* AsyncStorage.multiSet(multi_set_pairs, (err) => {
* AsyncStorage.multiMerge(multi_merge_pairs, (err) => {
* AsyncStorage.multiGet(['UID234','UID345'], (err, stores) => {
* stores.map( (result, i, store) => {
* let key = store[i][0];
* let val = store[i][1];
* console.log(key, val);
* });
* });
* });
* });
*
* // Console log results:
* // => UID234 {"name":"Chris","age":31,"traits":{"shoe_size":10,"hair":"brown","eyes":"blue"}}
* // => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}}
*
* See http://facebook.github.io/react-native/docs/asyncstorage.html#multimerge
*/
multiMerge: function(
keyValuePairs: Array<Array<string>>,

77
docs/accessibilityinfo.md
View File

@ -8,9 +8,7 @@ next: actionsheetios
previous: webview
---
Sometimes it's useful to know whether or not the device has a screen reader that is currently active. The
`AccessibilityInfo` API is designed for this purpose. You can use it to query the current state of the
screen reader as well as to register to be notified when the state of the screen reader changes.
Sometimes it's useful to know whether or not the device has a screen reader that is currently active. The `AccessibilityInfo` API is designed for this purpose. You can use it to query the current state of the screen reader as well as to register to be notified when the state of the screen reader changes.
Here's a small example illustrating how to use `AccessibilityInfo`:
@ -57,7 +55,6 @@ class ScreenReaderStatusExample extends React.Component {
}
```
### Methods
- [`fetch`](docs/accessibilityinfo.html#fetch)
@ -66,9 +63,6 @@ class ScreenReaderStatusExample extends React.Component {
- [`announceForAccessibility`](docs/accessibilityinfo.html#announceforaccessibility)
- [`removeEventListener`](docs/accessibilityinfo.html#removeeventlistener)
---
# Reference
@ -78,87 +72,86 @@ class ScreenReaderStatusExample extends React.Component {
### `fetch()`
```javascript
AccessibilityInfo.fetch(): Promise
AccessibilityInfo.fetch()
```
Query whether a screen reader is currently enabled. Returns a promise which
resolves to a boolean. The result is `true` when a screen reader is enabled
and `false` otherwise.
Query whether a screen reader is currently enabled. Returns a promise which resolves to a boolean. The result is `true` when a screen reader is enabled and `false` otherwise.
---
### `addEventListener()`
```javascript
AccessibilityInfo.addEventListener(eventName: ChangeEventName, handler: Function): Object
AccessibilityInfo.addEventListener(eventName, handler)
```
Add an event handler. See [Change Event Names](docs/accessibilityinfo.html#changeeventnames).
Add an event handler.
| Name | Type | Required | Description |
| - | - | - | - |
| eventName | string | Yes | Name of the event |
| handler | function | Yes | Event handler |
Supported events:
- `change`: Fires when the state of the screen reader changes. The argument
to the event handler is a boolean. The boolean is `true` when a screen
reader is enabled and `false` otherwise.
- `announcementFinished`: iOS-only event. Fires when the screen reader has
finished making an announcement. The argument to the event handler is a dictionary
with these keys:
- `announcement`: The string announced by the screen reader.
- `success`: A boolean indicating whether the announcement was successfully made.
---
### `setAccessibilityFocus()`
```javascript
AccessibilityInfo.setAccessibilityFocus(reactTag: number): void
AccessibilityInfo.setAccessibilityFocus(reactTag)
```
Set accessibility focus to a React component.
| Name | Type | Required | Description |
| - | - | - | - |
| reactTag | number | Yes | React component tag |
| Platform |
| - |
| iOS |
---
### `announceForAccessibility()`
```javascript
AccessibilityInfo.announceForAccessibility(announcement: string): void
AccessibilityInfo.announceForAccessibility(announcement)
```
Post a string to be announced by the screen reader.
| Name | Type | Required | Description |
| - | - | - | - |
| announcement | string | Yes | String to be announced |
| Platform |
| - |
| iOS |
---
### `removeEventListener()`
```javascript
AccessibilityInfo.removeEventListener(eventName: ChangeEventName, handler)
AccessibilityInfo.removeEventListener(eventName, handler)
```
Remove an event handler. See [Change Event Names](docs/accessibilityinfo.html#changeeventnames).
Remove an event handler.
| Name | Type | Required | Description |
| - | - | - | - |
| eventName | string | Yes | Name of the event |
| handler | function | Yes | Event handler |
## Change Event Names
### `change`
Fires when the state of the screen reader changes. The argument to the event handler is a boolean. The boolean is `true` when a screen reader is enabled and `false` otherwise.
### `announcementFinished`
Fires when the screen reader has finished making an announcement. The argument to the event handler is a dictionary with these keys:
- `announcement`: The string announced by the screen reader.
- `success`: A boolean indicating whether the announcement was successfully made.
| Platform |
| - |
| iOS |

36
docs/actionsheetios.md
View File

@ -30,9 +30,14 @@ Display action sheets and share sheets on iOS.
ActionSheetIOS.showActionSheetWithOptions(options, callback)
```
Display an iOS action sheet.
Display an iOS action sheet. The `options` object must contain one or more
of:
| Name | Type | Required | Description |
| - | - | - | - |
| options | object | Yes | See below. |
| callback | function | Yes | Provides index for the selected item. |
The `options` object must contain one or more of:
- `options` (array of strings) - a list of button titles (required)
- `cancelButtonIndex` (int) - index of cancel button in `options`
@ -56,10 +61,6 @@ ActionSheetIOS.showActionSheetWithOptions({
});
```
---
### `showShareActionSheetWithOptions()`
@ -68,29 +69,28 @@ ActionSheetIOS.showActionSheetWithOptions({
ActionSheetIOS.showShareActionSheetWithOptions(options, failureCallback, successCallback)
```
Display the iOS share sheet.
Display the iOS share sheet. The `options` object should contain
one or both of `message` and `url` and can additionally have
a `subject` or `excludedActivityTypes`:
| Name | Type | Required | Description |
| - | - | - | - |
| options | object | Yes | See below. |
| failureCallback | function | Yes | See below. |
| successCallback | function | Yes | See below. |
The `options` object should contain one or both of `message` and `url` and can additionally have a `subject` or `excludedActivityTypes`:
- `url` (string) - a URL to share
- `message` (string) - a message to share
- `subject` (string) - a subject for the message
- `excludedActivityTypes` (array) - the activities to exclude from the ActionSheet
NOTE: if `url` points to a local file, or is a base64-encoded
uri, the file it points to will be loaded and shared directly.
In this way, you can share images, videos, PDF files, etc.
> NOTE:
> If `url` points to a local file, or is a base64-encoded uri, the file it points to will be loaded and shared directly. In this way, you can share images, videos, PDF files, etc.
The 'failureCallback' function takes one parameter, an error object.
The only property defined on this object is an optional `stack` property
of type `string`.
The 'failureCallback' function takes one parameter, an error object. The only property defined on this object is an optional `stack` property of type `string`.
The 'successCallback' function takes two parameters:
- a boolean value signifying success or failure
- a string that, in the case of success, indicates the method of sharing

58
docs/alert.md
View File

@ -8,39 +8,26 @@ next: alertios
previous: actionsheetios
---
Launches an alert dialog with the specified title and message.
Use `Alert` to display an alert dialog.
Optionally provide a list of buttons. Tapping any button will fire the
respective onPress callback and dismiss the alert. By default, the only
button will be an 'OK' button.
This is an API that works both on iOS and Android and can show static alerts. To show an alert that prompts the user to enter some information, see [`AlertIOS`](docs/alertios.html), as entering text in an alert is common on iOS only.
This is an API that works both on iOS and Android and can show static
alerts. To show an alert that prompts the user to enter some information,
see `AlertIOS`; entering text in an alert is common on iOS only.
Optionally provide a list of buttons. Tapping any button will fire the respective `onPress` callback, and dismiss the alert. If no buttons are provided, a single 'OK' button will be displayed by default.
## iOS
On iOS, you can specify any number of buttons.
On iOS you can specify any number of buttons. Each button can optionally
specify a style, which is one of 'default', 'cancel' or 'destructive'.
On Android, at most three buttons can be specified. Android has a concept of a neutral, negative and a positive button:
## Android
- If you specify one button, it will be the 'positive' one (such as 'OK')
- Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
- Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
On Android at most three buttons can be specified. Android has a concept
of a neutral, negative and a positive button:
Alerts on Android can be dismissed by tapping outside of the alert box. This event can be handled by providing an optional `options` parameter, with an `onDismiss` callback property `{ onDismiss: () => {} }`.
- If you specify one button, it will be the 'positive' one (such as 'OK')
- Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
- Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
By default alerts on Android can be dismissed by tapping outside of the alert
box. This event can be handled by providing an optional `options` parameter,
with an `onDismiss` callback property `{ onDismiss: () => {} }`.
Alternatively, the dismissing behavior can be disabled altogether by providing
an optional `options` parameter with the `cancelable` property set to `false`
i.e. `{ cancelable: false }`
Alternatively, the dismissing behavior can be disabled altogether by providing an optional `options` parameter with the `cancelable` property set to `false`, i.e. `{ cancelable: false }`
Example usage:
```
// Works on both iOS and Android
Alert.alert(
@ -55,14 +42,10 @@ Alert.alert(
)
```
### Methods
- [`alert`](docs/alert.html#alert)
---
# Reference
@ -72,8 +55,25 @@ Alert.alert(
### `alert()`
```javascript
Alert.alert(title, message?, buttons?, options?, type?)
Alert.alert(title, [message], [buttons], [options])
```
Launches an alert dialog with the specified title, and optionally a message.
| Name | Type | Required | Description |
| - | - | - | - |
| title | string | Yes | Alert title |
| message | string | No | Alert message |
| buttons | array | No | Array of buttons |
| options | object | No | See below. |
The optional `buttons` array should be composed of objects with any of the following:
- `text` (string) - text to display for this button
- `onPress` (function) - callback to be fired when button is tapped
- `style` (string) - on iOS, specifies the button style, one of 'default', 'cancel', or 'destructive'
The `options` object may include the following keys:
- `onDismiss` - provide a callback function to handle dismissal on Android
- `cancelable` - set to false to disable the default dismissal behavior on Android

184
docs/alertios.md
View File

@ -7,8 +7,11 @@ permalink: docs/alertios.html
next: animated
previous: alert
---
`AlertIOS` provides functionality to create an iOS alert dialog with a
message or create a prompt for user input.
Use `AlertIOS` to display an alert dialog with a message or to create a prompt for user input on iOS. If you don't need to prompt for user input, we recommend using [`Alert.alert()`](docs/alert.html#alert) for cross-platform support.
### Examples
Creating an iOS alert:
@ -29,50 +32,6 @@ AlertIOS.prompt(
);
```
We recommend using the [`Alert.alert`](docs/alert.html) method for
cross-platform support if you don't need to create iOS-only prompts.
### Methods
- [`alert`](docs/alertios.html#alert)
- [`prompt`](docs/alertios.html#prompt)
### Type Definitions
- [`AlertType`](docs/alertios.html#alerttype)
- [`AlertButtonStyle`](docs/alertios.html#alertbuttonstyle)
- [`ButtonsArray`](docs/alertios.html#buttonsarray)
---
# Reference
## Methods
### `alert()`
```javascript
AlertIOS.alert(title: string, [message]: string, [callbackOrButtons]: ?(() => void), ButtonsArray, [type]: AlertType): [object Object]
```
Create and display a popup alert.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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. |
Example with custom buttons:
```javascript
@ -86,32 +45,6 @@ AlertIOS.alert(
);
```
---
### `prompt()`
```javascript
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.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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'. |
Example with custom buttons:
```javascript
@ -126,8 +59,6 @@ AlertIOS.prompt(
);
```
,
Example with the default button and a custom callback:
```javascript
@ -142,60 +73,118 @@ AlertIOS.prompt(
### Methods
- [`alert`](docs/alertios.html#alert)
- [`prompt`](docs/alertios.html#prompt)
### Type Definitions
- [`AlertType`](docs/alertios.html#alerttype)
- [`AlertButtonStyle`](docs/alertios.html#alertbuttonstyle)
- [`ButtonsArray`](docs/alertios.html#buttonsarray)
---
# Reference
## Methods
### `alert()`
```javascript
AlertIOS.alert(title, [message], [callbackOrButtons])
```
Create and display a popup alert with a title and an optional message.
If passed a function in the `callbackOrButtons` param, 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'. See [ButtonsArray](docs/alertios.html#buttonsarray)
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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 | function, [ButtonsArray](docs/alertios.html#buttonsarray) | No | This optional argument should be either a single-argument function or an [array of buttons](docs/alertios.html#buttonsarray). |
---
### `prompt()`
```javascript
AlertIOS.prompt(title, [message], [callbackOrButtons], [type], [defaultValue], [keyboardType])
```
Create and display a prompt to enter some text.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| title | string | Yes | The dialog's title. |
| message | string | No | An optional message that appears above the text input. |
| callbackOrButtons | function, [ButtonsArray](docs/alertios.html#buttonsarray) | No | This optional argument should be either a single-argument function or an [array of buttons](docs/alertios.html#buttonsarray). |
| type | [AlertType](docs/alertios.html#alerttype) | No | This configures the text input. |
| 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'. |
## Type Definitions
### AlertType
An Alert button type
An Alert button type.
| Type |
| - |
| $Enum |
| enum('default', 'plain-text', 'secure-text', 'login-password') |
**Constants:**
| Value | Description |
| - | - |
| default | Default alert with no inputs |
| plain-text | Plain text input alert |
| secure-text | Secure text input alert |
| login-password | Login and password alert |
| 'default' | Default alert with no inputs |
| 'plain-text' | Plain text input alert |
| 'secure-text' | Secure text input alert |
| 'login-password' | Login and password alert |
---
### AlertButtonStyle
An Alert button style
An Alert button style.
| Type |
| - |
| $Enum |
| enum('default', 'cancel', 'destructive') |
**Constants:**
| Value | Description |
| - | - |
| default | Default button style |
| cancel | Cancel button style |
| destructive | Destructive button style |
| 'default' | Default button style |
| 'cancel' | Cancel button style |
| 'destructive' | Destructive button style |
---
### ButtonsArray
Array of buttons
Array of objects that describe a button.
| Type |
| - |
| Array |
| array of objects |
**Properties:**
@ -205,16 +194,3 @@ Array of buttons
| [text] | string | Button label |
| [onPress] | function | Callback function when button pressed |
| [style] | [AlertButtonStyle](docs/alertios.html#alertbuttonstyle) | Button style |
**Constants:**
| Value | Description |
| - | - |
| text | Button label |
| onPress | Callback function when button pressed |
| style | Button style |

470
docs/animated.md
View File

@ -4,18 +4,13 @@ title: Animated
layout: docs
category: APIs
permalink: docs/animated.html
next: appregistry
next: animatedvalue
previous: alertios
---
The `Animated` library is designed to make animations fluid, powerful, and
easy to build and maintain. `Animated` focuses on declarative relationships
between inputs and outputs, with configurable transforms in between, and
simple `start`/`stop` methods to control time-based animation execution.
The `Animated` library is designed to make animations fluid, powerful, and easy to build and maintain. `Animated` focuses on declarative relationships between inputs and outputs, with configurable transforms in between, and simple `start`/`stop` methods to control time-based animation execution.
The simplest workflow for creating an animation is to create an
`Animated.Value`, hook it up to one or more style attributes of an animated
component, and then drive updates via animations using `Animated.timing()`:
The simplest workflow for creating an animation is to create an `Animated.Value`, hook it up to one or more style attributes of an animated component, and then drive updates via animations using `Animated.timing()`:
```javascript
Animated.timing( // Animate value over time
@ -26,72 +21,44 @@ Animated.timing( // Animate value over time
).start(); // Start the animation
```
Refer to the [Animations](docs/animations.html#animated-api) guide to see
additional examples of `Animated` in action.
Refer to the [Animations](docs/animations.html#animated-api) guide to see additional examples of `Animated` in action.
## Overview
There are two value types you can use with `Animated`:
- [`Animated.Value()`](docs/animated.html#value) for single values
- [`Animated.ValueXY()`](docs/animated.html#valuexy) for vectors
- [`Animated.Value()`](docs/animatedvalue.html) for single values
- [`Animated.ValueXY()`](docs/animatedvaluexy.html) for vectors
`Animated.Value` can bind to style properties or other props, and can be
interpolated as well. A single `Animated.Value` can drive any number of
properties.
`Animated.Value` can bind to style properties or other props, and can be interpolated as well. A single `Animated.Value` can drive any number of properties.
### Configuring animations
`Animated` provides three types of animation types. Each animation type
provides a particular animation curve that controls how your values animate
from their initial value to the final value:
`Animated` provides three types of animation types. Each animation type provides a particular animation curve that controls how your values animate from their initial value to the final value:
- [`Animated.decay()`](docs/animated.html#decay) starts with an initial
velocity and gradually slows to a stop.
- [`Animated.spring()`](docs/animated.html#spring) provides a simple
spring physics model.
- [`Animated.timing()`](docs/animated.html#timing) animates a value over time
using [easing functions](docs/easing.html).
- [`Animated.decay()`](docs/animated.html#decay) starts with an initial velocity and gradually slows to a stop.
- [`Animated.spring()`](docs/animated.html#spring) provides a simple spring physics model.
- [`Animated.timing()`](docs/animated.html#timing) animates a value over time using [easing functions](docs/easing.html).
In most cases, you will be using `timing()`. By default, it uses a symmetric
easeInOut curve that conveys the gradual acceleration of an object to full
speed and concludes by gradually decelerating to a stop.
In most cases, you will be using `timing()`. By default, it uses a symmetric easeInOut curve that conveys the gradual acceleration of an object to full speed and concludes by gradually decelerating to a stop.
### Working with animations
Animations are started by calling `start()` on your animation. `start()`
takes a completion callback that will be called when the animation is done.
If the animation finished running normally, the completion callback will be
invoked with `{finished: true}`. If the animation is done because `stop()`
was called on it before it could finish (e.g. because it was interrupted by a
gesture or another animation), then it will receive `{finished: false}`.
Animations are started by calling `start()` on your animation. `start()` takes a completion callback that will be called when the animation is done. If the animation finished running normally, the completion callback will be invoked with `{finished: true}`. If the animation is done because `stop()` was called on it before it could finish (e.g. because it was interrupted by a gesture or another animation), then it will receive `{finished: false}`.
### Using the native driver
By using the native driver, we send everything about the animation to native
before starting the animation, allowing native code to perform the animation
on the UI thread without having to go through the bridge on every frame.
Once the animation has started, the JS thread can be blocked without
affecting the animation.
By using the native driver, we send everything about the animation to native before starting the animation, allowing native code to perform the animation on the UI thread without having to go through the bridge on every frame. Once the animation has started, the JS thread can be blocked without affecting the animation.
You can use the native driver by specifying `useNativeDriver: true` in your
animation configuration. See the
[Animations](docs/animations.html#using-the-native-driver) guide to learn
more.
You can use the native driver by specifying `useNativeDriver: true` in your animation configuration. See the [Animations](docs/animations.html#using-the-native-driver) guide to learn more.
### Animatable components
Only animatable components can be animated. These special components do the
magic of binding the animated values to the properties, and do targeted
native updates to avoid the cost of the react render and reconciliation
process on every frame. They also handle cleanup on unmount so they are safe
by default.
Only animatable components can be animated. These special components do the magic of binding the animated values to the properties, and do targeted native updates to avoid the cost of the react render and reconciliation process on every frame. They also handle cleanup on unmount so they are safe by default.
- [`createAnimatedComponent()`](docs/animated.html#createanimatedcomponent)
can be used to make a component animatable.
- [`createAnimatedComponent()`](docs/animated.html#createanimatedcomponent) can be used to make a component animatable.
`Animated` exports the following animatable components using the above
wrapper:
`Animated` exports the following animatable components using the above wrapper:
- `Animated.Image`
- `Animated.ScrollView`
@ -102,27 +69,18 @@ wrapper:
Animations can also be combined in complex ways using composition functions:
- [`Animated.delay()`](docs/animated.html#delay) starts an animation after
a given delay.
- [`Animated.parallel()`](docs/animated.html#parallel) starts a number of
animations at the same time.
- [`Animated.sequence()`](docs/animated.html#sequence) starts the animations
in order, waiting for each to complete before starting the next.
- [`Animated.stagger()`](docs/animated.html#stagger) starts animations in
order and in parallel, but with successive delays.
- [`Animated.delay()`](docs/animated.html#delay) starts an animation after a given delay.
- [`Animated.parallel()`](docs/animated.html#parallel) starts a number of animations at the same time.
- [`Animated.sequence()`](docs/animated.html#sequence) starts the animations in order, waiting for each to complete before starting the next.
- [`Animated.stagger()`](docs/animated.html#stagger) starts animations in order and in parallel, but with successive delays.
Animations can also be chained together simply by setting the `toValue` of
one animation to be another `Animated.Value`. See
[Tracking dynamic values](docs/animations.html#tracking-dynamic-values) in
the Animations guide.
Animations can also be chained together simply by setting the `toValue` of one animation to be another `Animated.Value`. See [Tracking dynamic values](docs/animations.html#tracking-dynamic-values) in the Animations guide.
By default, if one animation is stopped or interrupted, then all other
animations in the group are also stopped.
By default, if one animation is stopped or interrupted, then all other animations in the group are also stopped.
### Combining animated values
You can combine two animated values via addition, multiplication, division,
or modulo to make a new animated value:
You can combine two animated values via addition, multiplication, division, or modulo to make a new animated value:
- [`Animated.add()`](docs/animated.html#add)
- [`Animated.divide()`](docs/animated.html#divide)
@ -131,29 +89,19 @@ or modulo to make a new animated value:
### Interpolation
The `interpolate()` function allows input ranges to map to different output
ranges. By default, it will extrapolate the curve beyond the ranges given,
but you can also have it clamp the output value. It uses lineal interpolation
by default but also supports easing functions.
The `interpolate()` function allows input ranges to map to different output ranges. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. It uses lineal interpolation by default but also supports easing functions.
- [`interpolate()`](docs/animated.html#interpolate)
- [`interpolate()`](docs/animatedvalue.html#interpolate)
Read more about interpolation in the
[Animation](docs/animations.html#interpolation) guide.
Read more about interpolation in the [Animation](docs/animations.html#interpolation) guide.
### Handling gestures and other events
Gestures, like panning or scrolling, and other events can map directly to
animated values using `Animated.event()`. This is done with a structured map
syntax so that values can be extracted from complex event objects. The first
level is an array to allow mapping across multiple args, and that array
contains nested objects.
Gestures, like panning or scrolling, and other events can map directly to animated values using `Animated.event()`. This is done with a structured map syntax so that values can be extracted from complex event objects. The first level is an array to allow mapping across multiple args, and that array contains nested objects.
- [`Animated.event()`](docs/animated.html#event)
For example, when working with horizontal scrolling gestures, you would do
the following in order to map `event.nativeEvent.contentOffset.x` to
`scrollX` (an `Animated.Value`):
For example, when working with horizontal scrolling gestures, you would do the following in order to map `event.nativeEvent.contentOffset.x` to `scrollX` (an `Animated.Value`):
```javascript
onScroll={Animated.event(
@ -167,27 +115,40 @@ the following in order to map `event.nativeEvent.contentOffset.x` to
)}
```
### Methods
- [`decay`](docs/animated.html#decay)
- [`timing`](docs/animated.html#timing)
- [`spring`](docs/animated.html#spring)
#### Configuring animations
- [`decay()`](docs/animated.html#decay)
- [`timing()`](docs/animated.html#timing)
- [`spring()`](docs/animated.html#spring)
#### Combining animated values
- [`add`](docs/animated.html#add)
- [`divide`](docs/animated.html#divide)
- [`multiply`](docs/animated.html#multiply)
- [`modulo`](docs/animated.html#modulo)
- [`diffClamp`](docs/animated.html#diffclamp)
#### Composing animations
- [`delay`](docs/animated.html#delay)
- [`sequence`](docs/animated.html#sequence)
- [`parallel`](docs/animated.html#parallel)
- [`stagger`](docs/animated.html#stagger)
- [`loop`](docs/animated.html#loop)
#### Handling gestures and other events
- [`event`](docs/animated.html#event)
- [`attachNativeEvent`](docs/animated.html#attachnativeevent)
- [`forkEvent`](docs/animated.html#forkevent)
- [`unforkEvent`](docs/animated.html#unforkevent)
#### Others
- [`loop`](docs/animated.html#loop)
- [`createAnimatedComponent`](docs/animated.html#createanimatedcomponent)
### Properties
@ -195,10 +156,6 @@ the following in order to map `event.nativeEvent.contentOffset.x` to
- [`ValueXY`](docs/animated.html#valuexy)
- [`Interpolation`](docs/animated.html#interpolation)
- [`Node`](docs/animated.html#node)
- [`createAnimatedComponent`](docs/animated.html#createanimatedcomponent)
- [`attachNativeEvent`](docs/animated.html#attachnativeevent)
---
@ -210,36 +167,42 @@ the following in order to map `event.nativeEvent.contentOffset.x` to
### `decay()`
```javascript
static decay(value, config)
Animated.decay(value, config)
```
Animates a value from an initial velocity to zero based on a decay coefficient.
Animates a value from an initial velocity to zero based on a decay
coefficient.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| value | AnimatedValue or AnimatedValueXY | Yes | Value to animate. |
| config | object | Yes | See below. |
Config is an object that may have the following options:
- `velocity`: Initial velocity. Required.
- `deceleration`: Rate of decay. Default 0.997.
- `isInteraction`: Whether or not this animation creates an "interaction handle" on the
`InteractionManager`. Default true.
- `useNativeDriver`: Uses the native driver when true. Default false.
- `velocity`: Initial velocity. Required.
- `deceleration`: Rate of decay. Default 0.997.
- `isInteraction`: Whether or not this animation creates an "interaction handle" on the
`InteractionManager`. Default true.
- `useNativeDriver`: Uses the native driver when true. Default false.
---
### `timing()`
```javascript
static timing(value, config)
Animated.timing(value, config)
```
Animates a value along a timed easing curve. The [`Easing`](docs/easing.html) module has tons of predefined curves, or you can use your own function.
Animates a value along a timed easing curve. The
[`Easing`](docs/easing.html) module has tons of predefined curves, or you
can use your own function.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| value | AnimatedValue or AnimatedValueXY | Yes | Value to animate. |
| config | object | Yes | See below. |
Config is an object that may have the following options:
@ -259,71 +222,62 @@ Config is an object that may have the following options:
### `spring()`
```javascript
static spring(value, config)
Animated.spring(value, config)
```
Animates a value according to an analytical spring model based on [damped harmonic oscillation](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator). Tracks velocity state to create fluid motions as the `toValue` updates, and can be chained together.
Animates a value according to an analytical spring model based on
[damped harmonic oscillation](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator).
Tracks velocity state to create fluid motions as the `toValue` updates, and
can be chained together.
**Parameters:**
Config is an object that may have the following options.
| Name | Type | Required | Description |
| - | - | - | - |
| value | AnimatedValue or AnimatedValueXY | Yes | Value to animate. |
| config | object | Yes | See below. |
Note that you can only define one of bounciness/speed, tension/friction, or
stiffness/damping/mass, but not more than one:
`config` is an object that may have the following options.
The friction/tension or bounciness/speed options match the spring model in
[Facebook Pop](https://github.com/facebook/pop), [Rebound](http://facebook.github.io/rebound/),
and [Origami](http://origami.design/).
Note that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:
- `friction`: Controls "bounciness"/overshoot. Default 7.
- `tension`: Controls speed. Default 40.
- `speed`: Controls speed of the animation. Default 12.
- `bounciness`: Controls bounciness. Default 8.
The friction/tension or bounciness/speed options match the spring model in [Facebook Pop](https://github.com/facebook/pop), [Rebound](http://facebook.github.io/rebound/), and [Origami](http://origami.design/).
Specifying stiffness/damping/mass as parameters makes `Animated.spring` use an
analytical spring model based on the motion equations of a [damped harmonic
oscillator](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator).
This behavior is slightly more precise and faithful to the physics behind
spring dynamics, and closely mimics the implementation in iOS's
CASpringAnimation primitive.
- `friction`: Controls "bounciness"/overshoot. Default 7.
- `tension`: Controls speed. Default 40.
- `speed`: Controls speed of the animation. Default 12.
- `bounciness`: Controls bounciness. Default 8.
- `stiffness`: The spring stiffness coefficient. Default 100.
- `damping`: Defines how the spring’s motion should be damped due to the forces of friction.
Default 10.
- `mass`: The mass of the object attached to the end of the spring. Default 1.
Specifying stiffness/damping/mass as parameters makes `Animated.spring` use an analytical spring model based on the motion equations of a [damped harmonic oscillator](https://en.wikipedia.org/wiki/Harmonic_oscillator#Damped_harmonic_oscillator). This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation primitive.
- `stiffness`: The spring stiffness coefficient. Default 100.
- `damping`: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.
- `mass`: The mass of the object attached to the end of the spring. Default 1.
Other configuration options are as follows:
- `velocity`: The initial velocity of the object attached to the spring. Default 0 (object
is at rest).
- `overshootClamping`: Boolean indiciating whether the spring should be clamped and not
bounce. Default false.
- `restDisplacementThreshold`: The threshold of displacement from rest below which the
spring should be considered at rest. Default 0.001.
- `restSpeedThreshold`: The speed at which the spring should be considered at rest in pixels
per second. Default 0.001.
- `delay`: Start the animation after delay (milliseconds). Default 0.
- `isInteraction`: Whether or not this animation creates an "interaction handle" on the
`InteractionManager`. Default true.
- `useNativeDriver`: Uses the native driver when true. Default false.
- `velocity`: The initial velocity of the object attached to the spring. Default 0 (object is at rest).
- `overshootClamping`: Boolean indiciating whether the spring should be clamped and not bounce. Default false.
- `restDisplacementThreshold`: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.
- `restSpeedThreshold`: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.
- `delay`: Start the animation after delay (milliseconds). Default 0.
- `isInteraction`: Whether or not this animation creates an "interaction handle" on the `InteractionManager`. Default true.
- `useNativeDriver`: Uses the native driver when true. Default false.
---
### `add()`
```javascript
static add(a, b)
Animated.add(a, b)
```
Creates a new Animated value composed from two Animated values added together.
Creates a new Animated value composed from two Animated values added
together.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| a | AnimatedValue | Yes | Operand. |
| b | AnimatedValue | Yes | Operand. |
@ -332,14 +286,18 @@ together.
### `divide()`
```javascript
static divide(a, b)
Animated.divide(a, b)
```
Creates a new Animated value composed by dividing the first Animated value
by the second Animated value.
Creates a new Animated value composed by dividing the first Animated value by the second Animated value.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| a | AnimatedValue | Yes | Operand. |
| b | AnimatedValue | Yes | Operand. |
---
@ -347,29 +305,36 @@ by the second Animated value.
### `multiply()`
```javascript
static multiply(a, b)
Animated.multiply(a, b)
```
Creates a new Animated value composed from two Animated values multiplied
together.
Creates a new Animated value composed from two Animated values multiplied together.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| a | AnimatedValue | Yes | Operand. |
| b | AnimatedValue | Yes | Operand. |
---
### `modulo()`
```javascript
static modulo(a, modulus)
Animated.modulo(a, modulus)
```
Creates a new Animated value that is the (non-negative) modulo of the
provided Animated value
Creates a new Animated value that is the (non-negative) modulo of the provided Animated value.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| a | AnimatedValue | Yes | Operand. |
| modulus | AnimatedValue | Yes | Operand. |
---
@ -377,48 +342,53 @@ provided Animated value
### `diffClamp()`
```javascript
static diffClamp(a, min, max)
Animated.diffClamp(a, min, max)
```
Create a new Animated value that is limited between 2 values. It uses the difference between the last value so even if the value is far from the bounds it will start changing when the value starts getting closer again. (`value = clamp(value + diff, min, max)`).
Create a new Animated value that is limited between 2 values. It uses the
difference between the last value so even if the value is far from the bounds
it will start changing when the value starts getting closer again.
(`value = clamp(value + diff, min, max)`).
This is useful with scroll events, for example, to show the navbar when
scrolling up and to hide it when scrolling down.
This is useful with scroll events, for example, to show the navbar when scrolling up and to hide it when scrolling down.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| a | AnimatedValue | Yes | Operand. |
| min | number | Yes | Minimum value. |
| max | number | Yes | Maximum value. |
---
### `delay()`
```javascript
static delay(time)
Animated.delay(time)
```
Starts an animation after the given delay.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| time | number | Yes | Delay in milliseconds. |
---
### `sequence()`
```javascript
static sequence(animations)
Animated.sequence(animations)
```
Starts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.
Starts an array of animations in order, waiting for each to complete
before starting the next. If the current running animation is stopped, no
following animations will be started.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| animations | array | Yes | Array of animations. |
@ -427,15 +397,19 @@ following animations will be started.
### `parallel()`
```javascript
static parallel(animations, config?)
Animated.parallel(animations, [config])
```
Starts an array of animations all at the same time. By default, if one
of the animations is stopped, they will all be stopped. You can override
this with the `stopTogether` flag through `config`.
Starts an array of animations all at the same time. By default, if one
of the animations is stopped, they will all be stopped. You can override
this with the `stopTogether` flag.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| animations | array | Yes | Array of animations. |
| config | object | No | An object with a `stopTogether` key (boolean). |
---
@ -443,106 +417,149 @@ this with the `stopTogether` flag.
### `stagger()`
```javascript
static stagger(time, animations)
Animated.stagger(time, animations)
```
Array of animations may run in parallel (overlap), but are started in
sequence with successive delays. Nice for doing trailing effects.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| time | number | Yes | Delay in milliseconds. |
| animations | array | Yes | Array of animations. |
---
### `loop()`
```javascript
static loop(animation)
Animated.loop(animation)
```
Loops a given animation continuously, so that each time it reaches the end, it resets and begins again from the start. Can specify number of times to loop using the key `iterations` in the config. Will loop without blocking the UI thread if the child animation is set to `useNativeDriver: true`. In addition, loops can prevent `VirtualizedList`-based components from rendering more rows while the animation is running. You can pass `isInteraction: false` in the child animation config to fix this.
Loops a given animation continuously, so that each time it reaches the
end, it resets and begins again from the start. Can specify number of
times to loop using the key `iterations` in the config. Will loop without
blocking the UI thread if the child animation is set to `useNativeDriver: true`.
In addition, loops can prevent `VirtualizedList`-based components from rendering
more rows while the animation is running. You can pass `isInteraction: false` in the
child animation config to fix this.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| animation | animation | Yes | Animation to loop. |
---
### `event()`
```javascript
static event(argMapping, config?)
Animated.event(argMapping, [config])
```
Takes an array of mappings and extracts values from each arg accordingly,
then calls `setValue` on the mapped outputs. e.g.
Takes an array of mappings and extracts values from each arg accordingly, then calls `setValue` on the mapped outputs. e.g.
```javascript
onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}, // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
]),
onScroll={Animated.event(
[{nativeEvent: {contentOffset: {x: this._scrollX}}}],
{listener: (event) => console.log(event)}, // Optional async listener
)}
...
onPanResponderMove: Animated.event([
null, // raw event arg ignored
{dx: this._panX}, // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
]),
```
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| argMapping | array | Yes | Array of mappings. |
| config | object | No | See below. |
Config is an object that may have the following options:
- `listener`: Optional async listener.
- `useNativeDriver`: Uses the native driver when true. Default false.
- `listener`: Optional async listener.
- `useNativeDriver`: Uses the native driver when true. Default false.
---
### `createAnimatedComponent()`
```javascript
createAnimatedComponent(component)
```
Make any React component Animatable. Used to create `Animated.View`, etc.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| component | component | Yes | React component |
---
### `attachNativeEvent()`
```javascript
attachNativeEvent(viewRef, eventName, argMapping)
```
Imperative API to attach an animated value to an event on a view. Prefer using `Animated.event` with `useNativeDrive: true` if possible.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| viewRef | any | Yes | View reference. |
| eventName | string | Yes | Event name. |
| argMapping | array | Yes | Array of mappings. |
---
### `forkEvent()`
```javascript
static forkEvent(event, listener)
Animated.forkEvent(event, listener)
```
Advanced imperative API for snooping on animated events that are passed in through props. Use values directly where possible.
Advanced imperative API for snooping on animated events that are passed in through props. Use
values directly where possible.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| event | event or function | Yes | Event. |
| listener | function | Yes | Handler. |
---
### `unforkEvent()`
```javascript
static unforkEvent(event, listener)
Animated.unforkEvent(event, listener)
```
Advanced imperative API for snooping on animated events that are passed in through props. Use values directly where possible.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| event | event or function | Yes | Event. |
| listener | function | Yes | Handler. |
## Properties
### Value
Standard value class for driving animations. Typically initialized with `new Animated.Value(0);`
See also `AnimatedValue.js`.
Standard value for driving animations.
| Type |
| - |
| AnimatedValue |
| [`AnimatedValue`](docs/animatedvalue.html) |
---
@ -550,21 +567,15 @@ See also `AnimatedValue.js`.
2D value class for driving 2D animations, such as pan gestures.
See also `AnimatedValueXY.js`.
| Type |
| - |
| AnimatedValueXY |
| [`AnimatedValueXY`](docs/animatedvaluexy.html) |
---
### Interpolation
Exported to use the Interpolation type in flow
See also `AnimatedInterpolation.js`.
Exported to use the Interpolation type in flow.
| Type |
| - |
@ -574,10 +585,9 @@ See also `AnimatedInterpolation.js`.
### Node
Exported for ease of type checking. All animated values derive from this class.
Exported for ease of type checking. All animated values derive from this class. See `AnimatedNode.js`.
| Type |
| - |
| AnimatedNode |

234
docs/animatedvalue.md Normal file
View File

@ -0,0 +1,234 @@
---
id: animatedvalue
title: AnimatedValue
layout: docs
category: APIs
permalink: docs/animatedvalue.html
next: animatedvaluexy
previous: animated
---
Standard value for driving animations. One `Animated.Value` can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling `setValue`) will stop any previous ones.
Typically initialized with `new Animated.Value(0);`
See also [`Animated`](docs/animated.html).
### Methods
- [`setValue`](docs/animatedvalue.html#setvalue)
- [`setOffset`](docs/animatedvalue.html#setoffset)
- [`flattenOffset`](docs/animatedvalue.html#flattenoffset)
- [`extractOffset`](docs/animatedvalue.html#extractoffset)
- [`addListener`](docs/animatedvalue.html#addlistener)
- [`removeListener`](docs/animatedvalue.html#removelistener)
- [`removeAllListeners`](docs/animatedvalue.html#removealllisteners)
- [`stopAnimation`](docs/animatedvalue.html#stopanimation)
- [`resetAnimation`](docs/animatedvalue.html#resetanimation)
- [`interpolate`](docs/animatedvalue.html#interpolate)
- [`animate`](docs/animatedvalue.html#animate)
- [`stopTracking`](docs/animatedvalue.html#stoptracking)
- [`track`](docs/animatedvalue.html#track)
---
# Reference
## Methods
### `setValue()`
```javascript
setValue(value)
```
Directly set the value. This will stop any animations running on the value and update all the bound properties.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| value | number | Yes | Value |
---
### `setOffset()`
```javascript
setOffset(offset)
```
Sets an offset that is applied on top of whatever value is set, whether via `setValue`, an animation, or `Animated.event`. Useful for compensating things like the start of a pan gesture.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| offset | number | Yes | Offset value |
---
### `flattenOffset()`
```javascript
flattenOffset()
```
Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.
---
### `extractOffset()`
```javascript
extractOffset()
```
Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.
---
### `addListener()`
```javascript
addListener(callback)
```
Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.
Returns a string that serves as an identifier for the listener.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | Yes | The callback function which will receive an object with a `value` key set to the new value. |
---
### `removeListener()`
```javascript
removeListener(id)
```
Unregister a listener. The `id` param shall match the identifier previously returned by `addListener()`.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| id | string | Yes | Id for the listener being removed. |
---
### `removeAllListeners()`
```javascript
removeAllListeners()
```
Remove all registered listeners.
---
### `stopAnimation()`
```javascript
stopAnimation([callback])
```
Stops any running animation or tracking. `callback` is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | No | A function that will receive the final value. |
---
### `resetAnimation()`
```javascript
resetAnimation([callback])
```
Stops any animation and resets the value to its original.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | No | A function that will receive the original value. |
---
### `interpolate()`
```javascript
interpolate(config)
```
Interpolates the value before updating the property, e.g. mapping 0-1 to 0-10.
See `AnimatedInterpolation.js`
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| config | object | Yes | See below. |
The `config` object is composed of the following keys:
- `inputRange`: an array of numbers
- `outputRange`: an array of numbers or strings
- `easing` (optional): a function that returns a number, given an input number
- `extrapolate` (optional): a string such as 'extend', 'identity', or 'clamp'
- `extrapolateLeft` (optional): a string such as 'extend', 'identity', or 'clamp'
- `extrapolateRight` (optional): a string such as 'extend', 'identity', or 'clamp'
---
### `animate()`
```javascript
animate(animation, callback)
```
Typically only used internally, but could be used by a custom Animation class.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| animation | Animation | Yes | See `Animation.js`. |
| callback | function | Yes | Callback function. |
---
### `stopTracking()`
```javascript
stopTracking()
```
Typically only used internally.
---
### `track()`
```javascript
track(tracking)
```
Typically only used internally.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| tracking | AnimatedNode | Yes | See `AnimatedNode.js` |

228
docs/animatedvaluexy.md Normal file
View File

@ -0,0 +1,228 @@
---
id: animatedvaluexy
title: AnimatedValueXY
layout: docs
category: APIs
permalink: docs/animatedvaluexy.html
next: appregistry
previous: animatedvalue
---
2D Value for driving 2D animations, such as pan gestures. Almost identical API to normal [`Animated.Value`](docs/animatedvalue.html), but multiplexed. Contains two regular `Animated.Value`s under the hood.
See also [`Animated`](docs/animated.html).
## Example
```javascript
class DraggableView extends React.Component {
constructor(props) {
super(props);
this.state = {
pan: new Animated.ValueXY(), // inits to zero
};
this.state.panResponder = PanResponder.create({
onStartShouldSetPanResponder: () => true,
onPanResponderMove: Animated.event([null, {
dx: this.state.pan.x, // x,y are Animated.Value
dy: this.state.pan.y,
}]),
onPanResponderRelease: () => {
Animated.spring(
this.state.pan, // Auto-multiplexed
{toValue: {x: 0, y: 0}} // Back to zero
).start();
},
});
}
render() {
return (
<Animated.View
{...this.state.panResponder.panHandlers}
style={this.state.pan.getLayout()}>
{this.props.children}
</Animated.View>
);
}
}
```
### Methods
- [`setValue`](docs/animatedvaluexy.html#setvalue)
- [`setOffset`](docs/animatedvaluexy.html#setoffset)
- [`flattenOffset`](docs/animatedvaluexy.html#flattenoffset)
- [`extractOffset`](docs/animatedvaluexy.html#extractoffset)
- [`addListener`](docs/animatedvaluexy.html#addlistener)
- [`removeListener`](docs/animatedvaluexy.html#removelistener)
- [`removeAllListeners`](docs/animatedvaluexy.html#removealllisteners)
- [`stopAnimation`](docs/animatedvaluexy.html#stopanimation)
- [`resetAnimation`](docs/animatedvaluexy.html#resetanimation)
- [`getLayout`](docs/animatedvaluexy.html#getlayout)
- [`getTranslateTransform`](docs/animatedvaluexy.html#gettranslatetransform)
---
# Reference
## Methods
### `setValue()`
```javascript
setValue(value)
```
Directly set the value. This will stop any animations running on the value and update all the bound properties.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| value | number | Yes | |
---
### `setOffset()`
```javascript
setOffset(offset)
```
Sets an offset that is applied on top of whatever value is set, whether via `setValue`, an animation, or `Animated.event`. Useful for compensating things like the start of a pan gesture.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| offset | number | Yes | |
---
### `flattenOffset()`
```javascript
flattenOffset()
```
Merges the offset value into the base value and resets the offset to zero. The final output of the value is unchanged.
---
### `extractOffset()`
```javascript
extractOffset()
```
Sets the offset value to the base value, and resets the base value to zero. The final output of the value is unchanged.
---
### `addListener()`
```javascript
addListener(callback)
```
Adds an asynchronous listener to the value so you can observe updates from animations. This is useful because there is no way to synchronously read the value because it might be driven natively.
Returns a string that serves as an identifier for the listener.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | Yes | The callback function which will receive an object with a `value` key set to the new value. |
---
### `removeListener()`
```javascript
removeListener(id)
```
Unregister a listener. The `id` param shall match the identifier previously returned by `addListener()`.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| id | string | Yes | Id for the listener being removed. |
---
### `removeAllListeners()`
```javascript
removeAllListeners()
```
Remove all registered listeners.
---
### `stopAnimation()`
```javascript
stopAnimation([callback])
```
Stops any running animation or tracking. `callback` is invoked with the final value after stopping the animation, which is useful for updating state to match the animation position with layout.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | No | A function that will receive the final value. |
---
### `resetAnimation()`
```javascript
resetAnimation([callback])
```
Stops any animation and resets the value to its original.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | function | No | A function that will receive the original value. |
---
### `getLayout()`
```javascript
getLayout()
```
Converts `{x, y}` into `{left, top}` for use in style, e.g.
```javascript
style={this.state.anim.getLayout()}
```
---
### `getTranslateTransform()`
```javascript
getTranslateTransform()
```
Converts `{x, y}` into a useable translation transform, e.g.
```javascript
style={{
transform: this.state.anim.getTranslateTransform()
}}
```

269
docs/appregistry.md
View File

@ -11,34 +11,25 @@ previous: animated
<div class="banner-crna-ejected">
<h3>Project with Native Code Required</h3>
<p>
This API only works in projects made with <code>react-native init</code>
or in those made with Create React Native App which have since ejected. For
more information about ejecting, please see
the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on
the Create React Native App repository.
This API only works in projects made with <code>react-native init</code> or in those made with Create React Native App which have since ejected. For more information about ejecting, please see the <a href="https://github.com/react-community/create-react-native-app/blob/master/EJECTING.md" target="_blank">guide</a> on the Create React Native App repository.
</p>
</div>
`AppRegistry` is the JS entry point to running all React Native apps. App
root components should register themselves with
`AppRegistry.registerComponent`, then the native system can load the bundle
for the app and then actually run the app when it's ready by invoking
`AppRegistry.runApplication`.
To "stop" an application when a view should be destroyed, call
`AppRegistry.unmountApplicationComponentAtRootTag` with the tag that was
passed into `runApplication`. These should always be used as a pair.
`AppRegistry` should be `require`d early in the `require` sequence to make
sure the JS execution environment is setup before other modules are
`require`d.
`AppRegistry` is the JavaScript entry point to running all React Native apps. App root components should register themselves with `AppRegistry.registerComponent()`, then the native system can load the bundle for the app and then actually run the app when it's ready by invoking `AppRegistry.runApplication()`.
To "stop" an application when a view should be destroyed, call `AppRegistry.unmountApplicationComponentAtRootTag()` with the tag that was passed into `runApplication()`. These should always be used as a pair.
`AppRegistry` should be `require`d early in the `require` sequence to make sure the JavaScript execution environment is set up before other modules are `require`d.
### Methods
- [`registerComponent`](docs/appregistry.html#registercomponent)
- [`runApplication`](docs/appregistry.html#runapplication)
- [`unmountApplicationComponentAtRootTag`](docs/appregistry.html#unmountapplicationcomponentatroottag)
- [`registerHeadlessTask`](docs/appregistry.html#registerheadlesstask)
- [`startHeadlessTask`](docs/appregistry.html#startheadlesstask)
- [`setWrapperComponentProvider`](docs/appregistry.html#setwrappercomponentprovider)
- [`registerConfig`](docs/appregistry.html#registerconfig)
- [`registerComponent`](docs/appregistry.html#registercomponent)
- [`registerRunnable`](docs/appregistry.html#registerrunnable)
- [`registerSection`](docs/appregistry.html#registersection)
- [`getAppKeys`](docs/appregistry.html#getappkeys)
@ -47,12 +38,6 @@ sure the JS execution environment is setup before other modules are
- [`getRunnable`](docs/appregistry.html#getrunnable)
- [`getRegistry`](docs/appregistry.html#getregistry)
- [`setComponentProviderInstrumentationHook`](docs/appregistry.html#setcomponentproviderinstrumentationhook)
- [`runApplication`](docs/appregistry.html#runapplication)
- [`unmountApplicationComponentAtRootTag`](docs/appregistry.html#unmountapplicationcomponentatroottag)
- [`registerHeadlessTask`](docs/appregistry.html#registerheadlesstask)
- [`startHeadlessTask`](docs/appregistry.html#startheadlesstask)
---
@ -61,143 +46,63 @@ sure the JS execution environment is setup before other modules are
## Methods
### `setWrapperComponentProvider()`
```javascript
static setWrapperComponentProvider(provider)
```
---
### `registerConfig()`
```javascript
static registerConfig(config)
```
---
### `registerComponent()`
```javascript
static registerComponent(appKey, componentProvider, section?)
AppRegistry.registerComponent(appKey, componentProvider, [section])
```
Registers an app's root component.
**Parameters:**
---
### `registerRunnable()`
```javascript
static registerRunnable(appKey, run)
```
---
### `registerSection()`
```javascript
static registerSection(appKey, component)
```
---
### `getAppKeys()`
```javascript
static getAppKeys()
```
---
### `getSectionKeys()`
```javascript
static getSectionKeys()
```
---
### `getSections()`
```javascript
static getSections()
```
---
### `getRunnable()`
```javascript
static getRunnable(appKey)
```
---
### `getRegistry()`
```javascript
static getRegistry()
```
---
### `setComponentProviderInstrumentationHook()`
```javascript
static setComponentProviderInstrumentationHook(hook)
```
| Name | Type | Required | Description |
| - | - | - | - |
| appKey | string | Yes | Application key. |
| componentProvider | function | Yes | A function that returns a React component or element. |
| section | boolean | No | Is this a section? |
---
### `runApplication()`
```javascript
static runApplication(appKey, appParameters)
AppRegistry.runApplication(appKey, appParameters)
```
Loads the JavaScript bundle and runs the app.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| appKey | string | Yes | Application key. |
| appParameters | any | Yes | Params. |
---
### `unmountApplicationComponentAtRootTag()`
```javascript
static unmountApplicationComponentAtRootTag(rootTag)
AppRegistry.unmountApplicationComponentAtRootTag(rootTag)
```
Stops an application when a view should be destroyed. The `rootTag` should match the tag that was passed into `runApplication()`. These should always be used as a pair.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| rootTag | number | Yes | React tag. |
---
### `registerHeadlessTask()`
```javascript
static registerHeadlessTask(taskKey, task)
AppRegistry.registerHeadlessTask(taskKey, task)
```
Register a headless task. A headless task is a bit of code that runs without a UI.
**Parameters:**
@ -213,7 +118,7 @@ Register a headless task. A headless task is a bit of code that runs without a U
### `startHeadlessTask()`
```javascript
static startHeadlessTask(taskId, taskKey, data)
AppRegistry.startHeadlessTask(taskId, taskKey, data)
```
Only called from native code. Starts a headless task.
@ -222,10 +127,108 @@ Only called from native code. Starts a headless task.
| 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 |
| 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. |
---
### `setWrapperComponentProvider()`
```javascript
AppRegistry.setWrapperComponentProvider(provider)
```
---
### `registerConfig()`
```javascript
AppRegistry.registerConfig(config)
```
---
### `registerRunnable()`
```javascript
AppRegistry.registerRunnable(appKey, run)
```
---
### `registerSection()`
```javascript
AppRegistry.registerSection(appKey, component)
```
---
### `getAppKeys()`
```javascript
AppRegistry.getAppKeys()
```
---
### `getSectionKeys()`
```javascript
AppRegistry.getSectionKeys()
```
---
### `getSections()`
```javascript
AppRegistry.getSections()
```
---
### `getRunnable()`
```javascript
AppRegistry.getRunnable(appKey)
```
---
### `getRegistry()`
```javascript
AppRegistry.getRegistry()
```
---
### `setComponentProviderInstrumentationHook()`
```javascript
AppRegistry.setComponentProviderInstrumentationHook(hook)
```

29
docs/appstate.md
View File

@ -8,11 +8,9 @@ next: asyncstorage
previous: appregistry
---
`AppState` can tell you if the app is in the foreground or background,
and notify you when the state changes.
`AppState` can tell you if the app is in the foreground or background, and notify you when the state changes.
AppState is frequently used to determine the intent and proper behavior when
handling push notifications.
App state is frequently used to determine the intent and proper behavior when handling push notifications.
### App States
@ -21,7 +19,7 @@ handling push notifications.
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
@ -70,8 +68,6 @@ This example will only ever appear to say "Current state is: active" because the
- [`removeEventListener`](docs/appstate.html#removeeventlistener)
---
# Reference
@ -84,9 +80,14 @@ This example will only ever appear to say "Current state is: active" because the
addEventListener(type, handler)
```
Add a handler to AppState changes by listening to the `change` event type and providing the handler.
Add a handler to AppState changes by listening to the `change` event type
and providing the handler
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| type | string | Yes | |
| handler | function | Yes | |
---
@ -96,9 +97,11 @@ and providing the handler
removeEventListener(type, handler)
```
Remove a handler by passing the `change` event type and the handler.
Remove a handler by passing the `change` event type and the handler
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| type | string | Yes | |
| handler | function | Yes | |

573
docs/asyncstorage.md
View File

@ -7,6 +7,7 @@ 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.
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.
@ -39,120 +40,7 @@ try {
}
```
### Methods
- [`getItem`](docs/asyncstorage.html#getitem)
- [`setItem`](docs/asyncstorage.html#setitem)
- [`removeItem`](docs/asyncstorage.html#removeitem)
- [`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)
- [`multiRemove`](docs/asyncstorage.html#multiremove)
- [`multiMerge`](docs/asyncstorage.html#multimerge)
---
# Reference
## Methods
### `getItem()`
```javascript
static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void)
```
Fetches an item for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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. |
---
### `setItem()`
```javascript
static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void)
```
Sets the value for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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. |
---
### `removeItem()`
```javascript
static removeItem(key: string, [callback]: ?(error: ?Error) => void)
```
Removes an item for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| key | string | Yes | Key of the item to remove. |
| callback | ?(error: ?Error) => void | No | Function that will be called with any error. |
---
### `mergeItem()`
```javascript
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.
> Note:
> This is not supported by all native implementations.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| 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:
Merging data:
```javascript
let UID123_object = {
@ -179,181 +67,8 @@ AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => {
// {'shoe_size':10,'hair':'brown','eyes':'blue'}}
```
---
### `clear()`
```javascript
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.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | ?(error: ?Error) => void | No | Function that will be called with any error. |
---
### `getAllKeys()`
```javascript
static getAllKeys([callback]: ?(error: ?Error, keys: ?Array<string>) => void)
```
Gets *all* keys known to your app; for all callers, libraries, etc.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | ?(error: ?Error, keys: ?Array<string>) => void | No | Function that will be called the keys found and any error. |
---
### `flushGetRequests()`
```javascript
static flushGetRequests(): [object Object]
```
Flushes any pending requests using a single batch call to get the data.
---
### `multiGet()`
```javascript
static multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => 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:
```
multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])
```
The method returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keys | Array<string> | Yes | Array of key for the items to get. |
| callback | ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => 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:
```javascript
AsyncStorage.getAllKeys((err, keys) => {
AsyncStorage.multiGet(keys, (err, stores) => {
stores.map((result, i, store) => {
// get at each store's key/value so you can work with it
let key = store[i][0];
let value = store[i][1];
});
});
});
```
---
### `multiSet()`
```javascript
static multiSet(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void)
```
Use this as a batch operation for storing multiple key-value pairs. When
the operation completes you'll get a single callback with any errors:
```
multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
```
The method returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keyValuePairs | Array<Array<string>> | Yes | Array of key-value array for the items to set. |
| callback | ?(errors: ?Array<Error>) => void | No | Function that will be called with an array of any key-specific errors found. |
---
### `multiRemove()`
```javascript
static multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)
```
Call this to batch the deletion of all keys in the `keys` array. Returns
a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keys | Array<string> | Yes | Array of key for the items to delete. |
| callback | ?(errors: ?Array<Error>) => void | No | Function that will be called an array of any key-specific errors found. |
Example:
```javascript
let keys = ['k1', 'k2'];
AsyncStorage.multiRemove(keys, (err) => {
// keys k1 & k2 removed, if they existed
// do most stuff after removal (if you want)
});
```
---
### `multiMerge()`
```javascript
static multiMerge(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void)
```
Batch operation to merge in existing and new values for a given set of
keys. This assumes that the values are stringified JSON. Returns a
`Promise` object.
**NOTE**: This is not supported by all native implementations.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keyValuePairs | Array<Array<string>> | Yes | Array of key-value array for the items to merge. |
| callback | ?(errors: ?Array<Error>) => void | No | Function that will be called with an array of any key-specific errors found. |
Example:
Multi merge example:
```javascript
@ -403,5 +118,287 @@ AsyncStorage.multiSet(multi_set_pairs, (err) => {
// => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}}
```
Fetching multiple items:
```javascript
AsyncStorage.getAllKeys((err, keys) => {
AsyncStorage.multiGet(keys, (err, stores) => {
stores.map((result, i, store) => {
// get at each store's key/value so you can work with it
let key = store[i][0];
let value = store[i][1];
});
});
});
```
Removing multiple items:
```javascript
let keys = ['k1', 'k2'];
AsyncStorage.multiRemove(keys, (err) => {
// keys k1 & k2 removed, if they existed
// do most stuff after removal (if you want)
});
```
### Methods
- [`getItem`](docs/asyncstorage.html#getitem)
- [`setItem`](docs/asyncstorage.html#setitem)
- [`removeItem`](docs/asyncstorage.html#removeitem)
- [`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)
- [`multiRemove`](docs/asyncstorage.html#multiremove)
- [`multiMerge`](docs/asyncstorage.html#multimerge)
---
# Reference
## Methods
### `getItem()`
```javascript
AsyncStorage.getItem(key, [callback])
```
Fetches an item for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| key | string | Yes | Key of the item to fetch. |
| callback | (error, result) => void | No | Function that will be called with a result if found or any error. |
---
### `setItem()`
```javascript
AsyncStorage.setItem(key, value, [callback])
```
Sets the value for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| key | string | Yes | Key of the item to set. |
| value | string | Yes | Value to set for the `key`. |
| callback | (error) => void | No | Function that will be called with any error. |
---
### `removeItem()`
```javascript
AsyncStorage.removeItem(key, [callback])
```
Removes an item for a `key` and invokes a callback upon completion.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| key | string | Yes | Key of the item to remove. |
| callback | (error) => void | No | Function that will be called with any error. |
---
### `mergeItem()`
```javascript
AsyncStorage.mergeItem(key, value, [callback])
```
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.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| key | string | Yes | Key of the item to modify. |
| value | string | Yes | New value to merge for the `key`. |
| callback | (error) => void | No | Function that will be called with any error. |
---
### `clear()`
```javascript
AsyncStorage.clear([callback])
```
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) => void | No | Function that will be called with any error. |
---
### `getAllKeys()`
```javascript
AsyncStorage.getAllKeys([callback])
```
Gets *all* keys known to your app; for all callers, libraries, etc.
Returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| callback | (error, keys) => void | No | Function that will be called with an array of keys found, and any error. |
---
### `flushGetRequests()`
```javascript
AsyncStorage.flushGetRequests()
```
Flushes any pending requests using a single batch call to get the data.
---
### `multiGet()`
```javascript
AsyncStorage.multiGet(keys, [callback])
```
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']])
```
The method returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keys | Array<string> | Yes | Array of key for the items to get. |
| callback | (errors, result) => void | No | Function that will be called with a key-value array of the results, plus an array of any key-specific errors found. |
---
### `multiSet()`
```javascript
AsyncStorage.multiSet(keyValuePairs, [callback])
```
Use this as a batch operation for storing multiple key-value pairs. When
the operation completes you'll get a single callback with any errors:
```
multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
```
The method returns a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keyValuePairs | Array<Array<string>> | Yes | Array of key-value array for the items to set. |
| callback | (errors) => void | No | Function that will be called with an array of any key-specific errors found. |
---
### `multiRemove()`
```javascript
AsyncStorage.multiRemove(keys, [callback])
```
Call this to batch the deletion of all keys in the `keys` array. Returns
a `Promise` object.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keys | Array<string> | Yes | Array of key for the items to delete. |
| callback | (errors) => void | No | Function that will be called an array of any key-specific errors found. |
---
### `multiMerge()`
```javascript
AsyncStorage.multiMerge(keyValuePairs, [callback])
```
Batch operation to merge in existing and new values for a given set of
keys. This assumes that the values are stringified JSON. Returns a
`Promise` object.
**NOTE**: This is not supported by all native implementations.
**Parameters:**
| Name | Type | Required | Description |
| - | - | - | - |
| keyValuePairs | Array<Array<string>> | Yes | Array of key-value array for the items to merge. |
| callback | (errors) => void | No | Function that will be called with an array of any key-specific errors found. |