From 6ad41a81bc5bd9d52f2989703e2d6311add6397c Mon Sep 17 00:00:00 2001 From: Hector Ramos Date: Fri, 17 Feb 2017 14:41:23 -0800 Subject: [PATCH] Clean up Animated docs Summary: After taking a look at the existing animation docs, I found that most of the documentation on using `Animated` was spread out throughout the Animations guide and the `Animated` API reference, without any particular structure in place. This PR aims to clean up the API reference, focusing on documenting all the provided methods exhaustively, and deferring to the Animations guide for long form examples and supporting content. The `Easing` module is referred to at various points in the API reference, so I decided to clean up this doc as well. easings.net provides some handy visualizations that should make it easier for the reader to understand what sort of easing curve each method provides. The site was built locally, and I verified all three documents render correctly. ![screencapture-localhost-8079-react-native-docs-animations-html-1487212173651](https://cloud.githubusercontent.com/assets/165856/23004694/d3db1670-f3ac-11e6-9d4e-0dd6079b7c5c.png) Closes https://github.com/facebook/react-native/pull/12410 Differential Revision: D4581314 Pulled By: hramos fbshipit-source-id: 27c0bce2afac8f084311b9d6113a2641133b42e5 --- .../js/AnimatedGratuitousApp/AnExSet.js | 7 +- .../Animated/src/AnimatedImplementation.js | 271 +++++--- Libraries/Animated/src/Easing.js | 139 +++- docs/Animations.md | 600 ++++++++---------- .../react-native/img/AnimatedFadeInView.gif | Bin 0 -> 44686 bytes 5 files changed, 581 insertions(+), 436 deletions(-) create mode 100644 website/src/react-native/img/AnimatedFadeInView.gif diff --git a/Examples/UIExplorer/js/AnimatedGratuitousApp/AnExSet.js b/Examples/UIExplorer/js/AnimatedGratuitousApp/AnExSet.js index 8e6e9a77d..7c96cdde8 100644 --- a/Examples/UIExplorer/js/AnimatedGratuitousApp/AnExSet.js +++ b/Examples/UIExplorer/js/AnimatedGratuitousApp/AnExSet.js @@ -98,11 +98,13 @@ class AnExSet extends React.Component { toValue: this.state.dismissY.interpolate({ // Track dismiss gesture inputRange: [0, 300], // and interpolate pixel distance outputRange: [1, 0], // to a fraction. - }) + }), + useNativeDriver: true, }).start(); }, onPanResponderMove: Animated.event( - [null, {dy: this.state.dismissY}] // track pan gesture + [null, {dy: this.state.dismissY}], // track pan gesture + {useNativeDriver: true} ), onPanResponderRelease: (e, gestureState) => { if (gestureState.dy > 100) { @@ -110,6 +112,7 @@ class AnExSet extends React.Component { } else { Animated.spring(this.props.openVal, { toValue: 1, // animate back open if released early + useNativeDriver: true, }).start(); } }, diff --git a/Libraries/Animated/src/AnimatedImplementation.js b/Libraries/Animated/src/AnimatedImplementation.js index 70b26ef47..525fb6f23 100644 --- a/Libraries/Animated/src/AnimatedImplementation.js +++ b/Libraries/Animated/src/AnimatedImplementation.js @@ -925,7 +925,9 @@ type ValueXYListenerCallback = (value: {x: number, y: number}) => void; /** * 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: + * `Animated.Value`s under the hood. + * + * #### Example * *```javascript * class DraggableView extends React.Component { @@ -2276,122 +2278,222 @@ var event = function( }; /** - * Animations are an important part of modern UX, and the `Animated` - * library is designed to make them fluid, powerful, and easy to build and - * maintain. + * 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 is to create an `Animated.Value`, hook it up to one or - * more style attributes of an animated component, and then drive updates either - * via animations, such as `Animated.timing`, or by hooking into gestures like - * panning or scrolling via `Animated.event`. `Animated.Value` can also bind to - * props other than style, and can be interpolated as well. Here is a basic - * example of a container view that will fade in when it's mounted: + * The simplest workflow for creating an animation is to 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 - * class FadeInView extends React.Component { - * constructor(props) { - * super(props); - * this.state = { - * fadeAnim: new Animated.Value(0), // init opacity 0 - * }; - * } - * componentDidMount() { - * Animated.timing( // Uses easing functions - * this.state.fadeAnim, // The value to drive - * {toValue: 1} // Configuration - * ).start(); // Don't forget start! - * } - * render() { - * return ( - * // Binds - * {this.props.children} - * - * ); - * } - * } - *``` + * ```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 + * ``` * - * Note that only animatable components can be animated. `View`, `Text`, and - * `Image` are already provided, and you can create custom ones with - * `createAnimatedComponent`. 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. + * Refer to the [Animations](docs/animations.html#animated-api) guide to see + * additional examples of `Animated` in action. * - * Animations are heavily configurable. Custom and pre-defined easing - * functions, delays, durations, decay factors, spring constants, and more can - * all be tweaked depending on the type of animation. + * ## Overview * - * A single `Animated.Value` can drive any number of properties, and each - * property can be run through an interpolation first. An interpolation maps - * input ranges to output ranges, typically using a linear interpolation but - * also supports easing functions. By default, it will extrapolate the curve - * beyond the ranges given, but you can also have it clamp the output value. + * There are two value types you can use with `Animated`: * - * For example, you may want to think about your `Animated.Value` as going from - * 0 to 1, but animate the position from 150px to 0px and the opacity from 0 to - * 1. This can easily be done by modifying `style` in the example above like so: + * - [`Animated.Value()`](docs/animated.html#value) for single values + * - [`Animated.ValueXY()`](docs/animated.html#valuexy) for vectors * - *```javascript - * style={{ - * opacity: this.state.fadeAnim, // Binds directly - * transform: [{ - * translateY: this.state.fadeAnim.interpolate({ - * inputRange: [0, 1], - * outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0 - * }), - * }], - * }}> - *``` + * `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. * - * Animations can also be combined in complex ways using composition functions - * such as `sequence` and `parallel`, and can also be chained together simply - * by setting the `toValue` of one animation to be another `Animated.Value`. + * ### Configuring animations * - * `Animated.ValueXY` is handy for 2D animations, like panning, and there are - * other helpful additions like `setOffset` and `getLayout` to aid with typical - * interaction patterns, like drag-and-drop. + * `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: * - * You can see more example usage in `AnimationExample.js`, the Gratuitous - * Animation App, and [Animations documentation guide](docs/animations.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. + * + * ### 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 + * } + * } + * }] + * )} + * ``` * - * Note that `Animated` is designed to be fully serializable so that animations - * can be run in a high performance way, independent of the normal JavaScript - * event loop. This does influence the API, so keep that in mind when it seems a - * little trickier to do something compared to a fully synchronous system. - * Checkout `Animated.Value.addListener` as a way to work around some of these - * limitations, but use it sparingly since it might have performance - * implications in the future. */ module.exports = { /** * Standard value class for driving animations. Typically initialized with * `new Animated.Value(0);` + * + * See also [`AnimatedValue`](docs/animated.html#animatedvalue). */ Value: AnimatedValue, /** * 2D value class for driving 2D animations, such as pan gestures. + * + * See also [`AnimatedValueXY`](docs/animated.html#animatedvaluexy). */ ValueXY: AnimatedValueXY, /** * exported to use the Interpolation type in flow + * + * See also [`AnimatedInterpolation`](docs/animated.html#animatedinterpolation). */ Interpolation: AnimatedInterpolation, /** * 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. + * - `useNativeDriver`: Uses the native driver when true. Default false. */ decay, /** - * Animates a value along a timed easing curve. The `Easing` module has tons - * of pre-defined 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. + * + * 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. + * - `useNativeDriver`: Uses the native driver when true. Default false. */ timing, /** - * Spring animation based on Rebound and Origami. Tracks velocity state to + * Spring animation based on Rebound and + * [Origami](https://facebook.github.io/origami/). 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: + * + * - `friction`: Controls "bounciness"/overshoot. Default 7. + * - `tension`: Controls speed. Default 40. + * - `useNativeDriver`: Uses the native driver when true. Default false. */ spring, @@ -2453,8 +2555,8 @@ module.exports = { stagger, /** - * 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( @@ -2467,6 +2569,11 @@ module.exports = { * {dx: this._panX}, // gestureState arg * ]), *``` + * + * Config is an object that may have the following options: + * + * - `listener`: Optional async listener. + * - `useNativeDriver`: Uses the native driver when true. Default false. */ event, diff --git a/Libraries/Animated/src/Easing.js b/Libraries/Animated/src/Easing.js index f358f7c79..03c409175 100644 --- a/Libraries/Animated/src/Easing.js +++ b/Libraries/Animated/src/Easing.js @@ -14,23 +14,81 @@ let ease; /** - * This class implements common easing functions. The math is pretty obscure, - * but this cool website has nice visual illustrations of what they represent: - * http://xaedes.de/dev/transitions/ + * The `Easing` module implements common easing functions. This module is used + * by [Animate.timing()](docs/animate.html#timing) to convey physically + * believable motion in animations. + * + * You can find a visualization of some common easing functions at + * http://easings.net/ + * + * ### Predefined animations + * + * The `Easing` module provides several predefined animations through the + * following methods: + * + * - [`back`](docs/easing.html#back) provides a simple animation where the + * object goes slightly back before moving forward + * - [`bounce`](docs/easing.html#bounce) provides a bouncing animation + * - [`ease`](docs/easing.html#ease) provides a simple inertial animation + * - [`elastic`](docs/easing.html#elastic) provides a simple spring interaction + * + * ### Standard functions + * + * Three standard easing functions are provided: + * + * - [`linear`](docs/easing.html#linear) + * - [`quad`](docs/easing.html#quad) + * - [`cubic`](docs/easing.html#cubic) + * + * The [`poly`](docs/easing.html#poly) function can be used to implement + * quartic, quintic, and other higher power functions. + * + * ### Additional functions + * + * Additional mathematical functions are provided by the following methods: + * + * - [`bezier`](docs/easing.html#bezier) provides a cubic bezier curve + * - [`circle`](docs/easing.html#circle) provides a circular function + * - [`sin`](docs/easing.html#sin) provides a sinusoidal function + * - [`exp`](docs/easing.html#exp) provides an exponential function + * + * The following helpers are used to modify other easing functions. + * + * - [`in`](docs/easing.html#in) runs an easing function forwards + * - [`inOut`](docs/easing.html#inout) makes any easing function symmetrical + * - [`out`](docs/easing.html#out) runs an easing function backwards */ class Easing { + /** + * A stepping function, returns 1 for any positive value of `n`. + */ static step0(n) { return n > 0 ? 1 : 0; } + /** + * A stepping function, returns 1 if `n` is greater than or equal to 1. + */ static step1(n) { return n >= 1 ? 1 : 0; } + /** + * A linear function, `f(t) = t`. Position correlates to elapsed time one to + * one. + * + * http://cubic-bezier.com/#0,0,1,1 + */ static linear(t) { return t; } + /** + * A simple inertial interaction, similar to an object slowly accelerating to + * speed. + * + * http://cubic-bezier.com/#.42,0,1,1 + */ static ease(t: number): number { if (!ease) { ease = Easing.bezier(0.42, 0, 1, 1); @@ -38,45 +96,91 @@ class Easing { return ease(t); } + /** + * A quadratic function, `f(t) = t * t`. Position equals the square of elapsed + * time. + * + * http://easings.net/#easeInQuad + */ static quad(t) { return t * t; } + /** + * A cubic function, `f(t) = t * t * t`. Position equals the cube of elapsed + * time. + * + * http://easings.net/#easeInCubic + */ static cubic(t) { return t * t * t; } + /** + * A power function. Position is equal to the Nth power of elapsed time. + * + * n = 4: http://easings.net/#easeInQuart + * n = 5: http://easings.net/#easeInQuint + */ static poly(n) { return (t) => Math.pow(t, n); } + /** + * A sinusoidal function. + * + * http://easings.net/#easeInSine + */ static sin(t) { return 1 - Math.cos(t * Math.PI / 2); } + /** + * A circular function. + * + * http://easings.net/#easeInCirc + */ static circle(t) { return 1 - Math.sqrt(1 - t * t); } + /** + * An exponential function. + * + * http://easings.net/#easeInExpo + */ static exp(t) { return Math.pow(2, 10 * (t - 1)); } /** - * A simple elastic interaction, similar to a spring. Default bounciness - * is 1, which overshoots a little bit once. 0 bounciness doesn't overshoot - * at all, and bounciness of N > 1 will overshoot about N times. + * A simple elastic interaction, similar to a spring oscillating back and + * forth. + * + * Default bounciness is 1, which overshoots a little bit once. 0 bounciness + * doesn't overshoot at all, and bounciness of N > 1 will overshoot about N + * times. + * + * http://easings.net/#easeInElastic * * Wolfram Plots: * - * http://tiny.cc/elastic_b_1 (default bounciness = 1) - * http://tiny.cc/elastic_b_3 (bounciness = 3) + * - http://tiny.cc/elastic_b_1 (bounciness = 1, default) + * - http://tiny.cc/elastic_b_3 (bounciness = 3) */ static elastic(bounciness: number = 1): (t: number) => number { const p = bounciness * Math.PI; return (t) => 1 - Math.pow(Math.cos(t * Math.PI / 2), 3) * Math.cos(t * p); } + /** + * Use with `Animated.parallel()` to create a simple effect where the object + * animates back slightly as the animation starts. + * + * Wolfram Plot: + * + * - http://tiny.cc/back_default (s = 1.70158, default) + */ static back(s: number): (t: number) => number { if (s === undefined) { s = 1.70158; @@ -84,6 +188,11 @@ class Easing { return (t) => t * t * ((s + 1) * t - s); } + /** + * Provides a simple bouncing effect. + * + * http://easings.net/#easeInBounce + */ static bounce(t: number): number { if (t < 1 / 2.75) { return 7.5625 * t * t; @@ -103,6 +212,13 @@ class Easing { return 7.5625 * t * t + 0.984375; } + /** + * Provides a cubic bezier curve, equivalent to CSS Transitions' + * `transition-timing-function`. + * + * A useful tool to visualize cubic bezier curves can be found at + * http://cubic-bezier.com/ + */ static bezier( x1: number, y1: number, @@ -113,6 +229,9 @@ class Easing { return _bezier(x1, y1, x2, y2); } + /** + * Runs an easing function forwards. + */ static in( easing: (t: number) => number, ): (t: number) => number { @@ -129,7 +248,9 @@ class Easing { } /** - * Makes any easing function symmetrical. + * Makes any easing function symmetrical. The easing function will run + * forwards for half of the duration, then backwards for the rest of the + * duration. */ static inOut( easing: (t: number) => number, diff --git a/docs/Animations.md b/docs/Animations.md index a738dd3cc..04b41ef67 100644 --- a/docs/Animations.md +++ b/docs/Animations.md @@ -8,103 +8,128 @@ next: accessibility previous: handling-touches --- -Fluid, meaningful animations are essential to the mobile user experience. Like -everything in React Native, Animation APIs for React Native are currently under -development, but have started to coalesce around two complementary systems: -`LayoutAnimation` for animated global layout transactions, and `Animated` for -more granular and interactive control of specific values. +Animations are very important to create a great user experience. +Stationary objects must overcome inertia as they start moving. +Objects in motion have momentum and rarely come to a stop immediately. +Animations allow you to convey physically believable motion in your interface. -### Animated ### +React Native provides two complementary animation systems: +[`Animated`](docs/animations.html#animated-api) for granular and interactive control of specific values, and +[`LayoutAnimation`](docs/animations.html#layoutanimation) for animated global layout transactions. -The `Animated` library is designed to make it very easy to concisely express a -wide variety of interesting animation and interaction patterns in a very -performant way. `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. For example, a complete -component with a simple spring bounce on mount looks like this: +## `Animated` API + +The [`Animated`](docs/animated.html) API is designed to make it very easy to concisely express a wide variety of interesting animation and interaction patterns in a very performant way. +`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. + +`Animated` exports four animatable component types: `View`, `Text`, `Image`, and `ScrollView`, but you can also create your own using `Animated.createAnimatedComponent()`. + +For example, a container view that fades in when it is mounted may look like this: ```javascript -class Playground extends React.Component { +// FadeInView.js +import React, { Component } from 'react'; +import { + Animated, +} from 'react-native'; + +class FadeInView extends Component { constructor(props) { super(props); this.state = { - bounceValue: new Animated.Value(0), + fadeAnim: new Animated.Value(0), // Initial value for opacity: 0 }; } + componentDidMount() { + Animated.timing( // Animate over time + this.state.fadeAnim, // The animated value to drive + { + toValue: 1, // Animate to opacity: 1, or fully opaque + } + ).start(); // Starts the animation + } render() { return ( - + > + {this.props.children} + ); } - componentDidMount() { - this.state.bounceValue.setValue(1.5); // Start large - Animated.spring( // Base: spring, decay, timing - this.state.bounceValue, // Animate `bounceValue` - { - toValue: 0.8, // Animate to smaller size - friction: 1, // Bouncier spring - } - ).start(); // Start the animation - } +} + +module.exports = FadeInView; +``` + +You can then use your `FadeInView` in place of a `View` in your components, like so: + +```javascript +render() { + return ( + + Fading in + + ) } ``` -`bounceValue` is initialized as part of `state` in the constructor, and mapped -to the scale transform on the image. Behind the scenes, the numeric value is -extracted and used to set scale. When the component mounts, the scale is set to -1.5 and then a spring animation is started on `bounceValue` which will update -all of its dependent mappings on each frame as the spring animates (in this -case, just the scale). This is done in an optimized way that is faster than -calling `setState` and re-rendering. Because the entire configuration is -declarative, we will be able to implement further optimizations that serialize -the configuration and runs the animation on a high-priority thread. +![FadeInView](img/AnimatedFadeInView.gif) -#### Core API +Let's break down what's happening here. +In the `FadeInView` constructor, a new `Animated.Value` called `fadeAnim` is initialized as part of `state`. +The opacity property on the `View` is mapped to this animated value. +Behind the scenes, the numeric value is extracted and used to set opacity. -Most everything you need hangs directly off the `Animated` module. This -includes two value types, `Value` for single values and `ValueXY` for vectors, -three animation types, `spring`, `decay`, and `timing`, and three component -types, `View`, `Text`, and `Image`. You can make any other component animated with -`Animated.createAnimatedComponent`. +When the component mounts, the opacity is set to 0. +Then, an easing animation is started on the `fadeAnim` animated value, +which will update all of its dependent mappings (in this case, just the opacity) on each frame as the value animates to the final value of 1. -The three animation types can be used to create almost any animation curve you -want because each can be customized: +This is done in an optimized way that is faster than calling `setState` and re-rendering. +Because the entire configuration is declarative, we will be able to implement further optimizations that serialize the configuration and runs the animation on a high-priority thread. -* `spring`: Simple single-spring physics model that matches [Origami](https://facebook.github.io/origami/). - * `friction`: Controls "bounciness"/overshoot. Default 7. - * `tension`: Controls speed. Default 40. -* `decay`: Starts with an initial velocity and gradually slows to a stop. - * `velocity`: Initial velocity. Required. - * `deceleration`: Rate of decay. Default 0.997. -* `timing`: Maps time range to easing value. - * `duration`: Length of animation (milliseconds). Default 500. - * `easing`: Easing function to define curve. See `Easing` module for several - predefined functions. iOS default is `Easing.inOut(Easing.ease)`. - * `delay`: Start the animation after delay (milliseconds). Default 0. +### Configuring animations -Animations are started by calling `start`. `start` takes a completion callback -that will be called when the animation is done. If the animation is done -because it finished running normally, the completion callback will be invoked -with `{finished: true}`, but 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 heavily configurable. Custom and predefined easing functions, delays, durations, decay factors, spring constants, and more can all be tweaked depending on the type of animation. -#### Composing Animations +`Animated` provides several animation types, the most commonly used one being [`Animated.timing()`](docs/animated.html#timing). +It supports animating a value over time using one of various predefined easing functions, or you can use your own. +Easing functions are typically used in animation to convey gradual acceleration and deceleration of objects. -Animations can also be composed with `parallel`, `sequence`, `stagger`, and -`delay`, each of which simply take an array of animations to execute and -automatically calls start/stop as appropriate. For example: +By default, `timing` will use a easeInOut curve that conveys gradual acceleration to full speed and concludes by gradually decelerating to a stop. +You can specify a different easing function by passing a `easing` parameter. +Custom `duration` or even a `delay` before the animation starts is also supported. + +For example, if we want to create a 2-second long animation of an object that slightly backs up before moving to its final position: ```javascript -Animated.sequence([ // spring to start and twirl after decay finishes +Animated.timing( + this.state.xPosition, + { + toValue: 100, + easing: Easing.back, + duration: 2000, + } +).start(); +``` + +Take a look at the [Configuring animations](docs/animated.html#configuring-animations) section of the `Animated` API reference to learn more about all the config parameters supported by the built-in animations. + +### Composing animations + +Animations can be combined and played in sequence or in parallel. +Sequential animations can play immediately after the previous animation has finished, +or they can start after a specified delay. +The `Animated` API provides several methods, such as `sequence()` and `delay()`, +each of which simply take an array of animations to execute and automatically calls `start()`/`stop()` as needed. + +For example, the following animation coasts to a stop, then it springs back while twirling in parallel: + +```javascript +Animated.sequence([ // decay, then spring to start and twirl Animated.decay(position, { // coast to a stop velocity: {x: gestureState.vx, y: gestureState.vy}, // velocity from gesture release deceleration: 0.997, @@ -120,15 +145,35 @@ Animated.sequence([ // spring to start and twirl after decay finishes ]).start(); // start the sequence group ``` -By default, if one animation is stopped or interrupted, then all other -animations in the group are also stopped. Parallel has a `stopTogether` option -that can be set to `false` to disable this. +If one animation is stopped or interrupted, then all other animations in the group are also stopped. +`Animated.parallel` has a `stopTogether` option that can be set to `false` to disable this. -#### Interpolation +You can find a full list of composition methods in the [Composing animations](docs/animated.html#composing-animations) section of the `Animated` API reference. -Another powerful part of the `Animated` API is the `interpolate` function. It -allows input ranges to map to different output ranges. For example, a simple -mapping to convert a 0-1 range to a 0-100 range would be +### Combining animated values + +You can [combine two animated values](docs/animated.html#combining-animated-values) via addition, multiplication, division, or modulo to make a new animated value. + +There are some cases where an animated value needs to invert another animated value for calculation. +An example is inverting a scale (2x --> 0.5x): + +```javascript +const a = Animated.Value(1); +const b = Animated.divide(1, a); + +Animated.spring(a, { + toValue: 2, +}).start(); +``` + +### Interpolation + +Each property can be run through an interpolation first. +An interpolation maps input ranges to output ranges, +typically using a linear interpolation but also supports easing functions. +By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value. + +A simple mapping to convert a 0-1 range to a 0-100 range would be: ```javascript value.interpolate({ @@ -137,11 +182,24 @@ value.interpolate({ }); ``` -`interpolate` supports multiple range segments as well, which is handy for -defining dead zones and other handy tricks. For example, to get an negation -relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then -back down to zero at 100 followed by a dead-zone that remains at 0 for -everything beyond that, you could do: +For example, you may want to think about your `Animated.Value` as going from 0 to 1, +but animate the position from 150px to 0px and the opacity from 0 to 1. +This can easily be done by modifying `style` from the example above like so: + +```javascript + style={{ + opacity: this.state.fadeAnim, // Binds directly + transform: [{ + translateY: this.state.fadeAnim.interpolate({ + inputRange: [0, 1], + outputRange: [150, 0] // 0 : 150, 0.5 : 75, 1 : 0 + }), + }], + }} +``` + +[`interpolate()`](docs/animated.html#interpolate) supports multiple range segments as well, which is handy for defining dead zones and other handy tricks. +For example, to get an negation relationship at -300 that goes to 0 at -100, then back up to 1 at 0, and then back down to zero at 100 followed by a dead-zone that remains at 0 for everything beyond that, you could do: ```javascript value.interpolate({ @@ -152,6 +210,7 @@ value.interpolate({ Which would map like so: +``` Input | Output ------|------- -400| 450 @@ -164,8 +223,9 @@ Input | Output 100| 0 101| 0 200| 0 +``` -`interpolate` also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do: +`interpolate()` also supports mapping to strings, allowing you to animate colors as well as values with units. For example, if you wanted to animate a rotation you could do: ```javascript value.interpolate({ @@ -174,23 +234,18 @@ value.interpolate({ }) ``` -`interpolation` also supports arbitrary easing functions, many of which are -already implemented in the -[`Easing`](https://github.com/facebook/react-native/blob/master/Libraries/Animation/Animated/Easing.js) -class including quadratic, exponential, and bezier curves as well as functions -like step and bounce. `interpolation` also has configurable behavior for -extrapolating the `outputRange`. You can set the extrapolation by setting the `extrapolate`, -`extrapolateLeft` or `extrapolateRight` options. The default value is -`extend` but you can use `clamp` to prevent the output value from exceeding -`outputRange`. +`interpolate()` also supports arbitrary easing functions, many of which are already implemented in the +[`Easing`](docs/easing.html) module. +`interpolate()` also has configurable behavior for extrapolating the `outputRange`. +You can set the extrapolation by setting the `extrapolate`, `extrapolateLeft`, or `extrapolateRight` options. +The default value is `extend` but you can use `clamp` to prevent the output value from exceeding `outputRange`. -#### Tracking Dynamic Values +### Tracking dynamic values -Animated values can also track other values. Just set the `toValue` of an -animation to another animated value instead of a plain number, for example with -spring physics for an interaction like "Chat Heads", or via `timing` with -`duration: 0` for rigid/instant tracking. They can also be composed with -interpolations: +Animated values can also track other values. +Just set the `toValue` of an animation to another animated value instead of a plain number. +For example, a "Chat Heads" animation like the one used by Messenger on Android could be implemented with a `spring()` pinned on another animated value, or with `timing()` and a `duration` of 0 for rigid tracking. +They can also be composed with interpolations: ```javascript Animated.spring(follower, {toValue: leader}).start(); @@ -202,66 +257,121 @@ Animated.timing(opacity, { }).start(); ``` -`ValueXY` is a handy way to deal with 2D interactions, such as panning/dragging. -It is a simple wrapper that basically just contains two `Animated.Value` -instances and some helper functions that call through to them, making `ValueXY` -a drop-in replacement for `Value` in many cases. For example, in the code -snippet above, `leader` and `follower` could both be of type `ValueXY` and the x -and y values will both track as you would expect. +The `leader` and `follower` animated values would be implemented using `Animated.ValueXY()`. +`ValueXY` is a handy way to deal with 2D interactions, such as panning or dragging. +It is a simple wrapper that basically contains two `Animated.Value` instances and some helper functions that call through to them, +making `ValueXY` a drop-in replacement for `Value` in many cases. +It allows us to track both x and y values in the example above. -#### Input Events +### Tracking gestures -`Animated.event` is the input side of the Animated API, allowing gestures and -other events to map directly to animated values. 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. In the example, you can see that `scrollX` maps to -`event.nativeEvent.contentOffset.x` (`event` is normally the first arg to the -handler), and `pan.x` and `pan.y` map to `gestureState.dx` and `gestureState.dy`, -respectively (`gestureState` is the second arg passed to the `PanResponder` handler). +Gestures, like panning or scrolling, and other events can map directly to animated values using [`Animated.event`](docs/animated.html#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. + +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}}}] -)} -onPanResponderMove={Animated.event([ - null, // ignore the native event + onScroll={Animated.event( + // scrollX = e.nativeEvent.contentOffset.x + [{ nativeEvent: { + contentOffset: { + x: scrollX + } + } + }] + )} +``` + +When using `PanResponder`, you could use the following code to extract the x and y positions from `gestureState.dx` and `gestureState.dy`. +We use a `null` in the first position of the array, as we are only interested in the second argument passed to the `PanResponder` handler, +which is the `gestureState`. + +```javascript +onPanResponderMove={Animated.event( + [null, // ignore the native event // extract dx and dy from gestureState // like 'pan.x = gestureState.dx, pan.y = gestureState.dy' {dx: pan.x, dy: pan.y} -]); +])} ``` -#### Responding to the Current Animation Value +### Responding to the current animation value -You may notice that there is no obvious way to read the current value while -animating - this is because the value may only be known in the native runtime -due to optimizations. If you need to run JavaScript in response to the current -value, there are two approaches: +You may notice that there is no obvious way to read the current value while animating. +This is because the value may only be known in the native runtime due to optimizations. +If you need to run JavaScript in response to the current value, there are two approaches: -- `spring.stopAnimation(callback)` will stop the animation and invoke `callback` -with the final value - this is useful when making gesture transitions. -- `spring.addListener(callback)` will invoke `callback` asynchronously while the -animation is running, providing a recent value. This is useful for triggering -state changes, for example snapping a bobble to a new option as the user drags -it closer, because these larger state changes are less sensitive to a few frames -of lag compared to continuous gestures like panning which need to run at 60fps. +- `spring.stopAnimation(callback)` will stop the animation and invoke `callback` with the final value. This is useful when making gesture transitions. +- `spring.addListener(callback)` will invoke `callback` asynchronously while the animation is running, providing a recent value. + This is useful for triggering state changes, + for example snapping a bobble to a new option as the user drags it closer, + because these larger state changes are less sensitive to a few frames of lag compared to continuous gestures like panning which need to run at 60 fps. -#### Future Work +`Animated` is designed to be fully serializable so that animations can be run in a high performance way, independent of the normal JavaScript event loop. +This does influence the API, so keep that in mind when it seems a little trickier to do something compared to a fully synchronous system. +Check out `Animated.Value.addListener` as a way to work around some of these limitations, +but use it sparingly since it might have performance implications in the future. -As previously mentioned, we're planning on optimizing Animated under the hood to -make it even more performant. We would also like to experiment with more -declarative and higher level gestures and triggers, such as horizontal vs. -vertical panning. +### Using the native driver -The above API gives a powerful tool for expressing all sorts of animations in a -concise, robust, and performant way. Check out more example code in -[UIExplorer/AnimationExample](https://github.com/facebook/react-native/tree/master/Examples/UIExplorer/js/AnimatedGratuitousApp). Of course there may still be times where `Animated` -doesn't support what you need, and the following sections cover other animation -systems. +The `Animated` API is designed to be serializable. +By using the [native driver](http://facebook.github.io/react-native/blog/2017/02/14/using-native-driver-for-animated.html), +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. -### LayoutAnimation +Using the native driver for normal animations is quite simple. +Just add `useNativeDriver: true` to the animation config when starting it. + +```javascript +Animated.timing(this.state.animatedValue, { + toValue: 1, + duration: 500, + useNativeDriver: true, // <-- Add this +}).start(); +``` + +Animated values are only compatible with one driver so if you use native driver when starting an animation on a value, +make sure every animation on that value also uses the native driver. + +The native driver also works with `Animated.event`. +This is specially useful for animations that follow the scroll position as without the native driver, +the animation will always run a frame behind the gesture due to the async nature of React Native. + +```javascript + + {content} + +``` + +You can see the native driver in action by running the [UIExplorer sample app](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/), +then loading the Native Animated Example. +You can also take a look at the [source code](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/js/NativeAnimationsExample.js) to learn how these examples were produced. + +#### Caveats + +Not everything you can do with `Animated` is currently supported by the native driver. +The main limitation is that you can only animate non-layout properties: +things like `transform`, `opacity` and `backgroundColor` will work, but flexbox and position properties will not. +When using `Animated.event`, it will only work with direct events and not bubbling events. +This means it does not work with `PanResponder` but does work with things like `ScrollView#onScroll`. + +### Additional examples + +The UIExplorer sample app has various examples of `Animated` in use: + +- [AnimatedGratuitousApp](https://github.com/facebook/react-native/tree/master/Examples/UIExplorer/js/AnimatedGratuitousApp) +- [NativeAnimationsExample](https://github.com/facebook/react-native/blob/master/Examples/UIExplorer/js/NativeAnimationsExample.js) + +## `LayoutAnimation` API `LayoutAnimation` allows you to globally configure `create` and `update` animations that will be used for all views in the next render/layout cycle. @@ -324,7 +434,9 @@ This example uses a preset value, you can customize the animations as you need, see [LayoutAnimation.js](https://github.com/facebook/react-native/blob/master/Libraries/LayoutAnimation/LayoutAnimation.js) for more information. -### requestAnimationFrame +## Additional notes + +### `requestAnimationFrame` `requestAnimationFrame` is a polyfill from the browser that you might be familiar with. It accepts a function as its only argument and calls that @@ -333,165 +445,7 @@ animations that underlies all of the JavaScript-based animation APIs. In general, you shouldn't need to call this yourself - the animation APIs will manage frame updates for you. -### react-tween-state (Not recommended - use [Animated](docs/animations.html#animated) instead) - -[react-tween-state](https://github.com/chenglou/react-tween-state) is a -minimal library that does exactly what its name suggests: it *tweens* a -value in a component's state, starting at a **from** value and ending at -a **to** value. This means that it generates the values in between those -two values, and it sets the state on every `requestAnimationFrame` with -the intermediary value. - -> Tweening definition from [Wikipedia](https://en.wikipedia.org/wiki/Inbetweening) -> -> "... tweening is the process of generating intermediate frames between two -> images to give the appearance that the first image evolves smoothly -> into the second image. [Tweens] are the drawings between the key -> frames which help to create the illusion of motion." - -The most obvious way to animate from one value to another is linearly: -you subtract the end value from the start value and divide the result by -the number of frames over which the animation occurs, and then add that -value to the current value on each frame until the end value is reached. -Linear easing often looks awkward and unnatural, so react-tween-state -provides a selection of popular [easing functions](http://easings.net/) -that can be applied to make your animations more pleasing. - -This library does not ship with React Native - in order to use it on -your project, you will need to install it with `npm i react-tween-state ---save` from your project directory. - -```javascript -import tweenState from 'react-tween-state'; -import reactMixin from 'react-mixin'; // https://github.com/brigand/react-mixin - -class App extends React.Component { - constructor(props) { - super(props); - this.state = { opacity: 1 }; - this._animateOpacity = this._animateOpacity.bind(this); - } - - _animateOpacity() { - this.tweenState('opacity', { - easing: tweenState.easingTypes.easeOutQuint, - duration: 1000, - endValue: this.state.opacity === 0.2 ? 1 : 0.2, - }); - } - - render() { - return ( - - - this._box = component} - style={{width: 200, height: 200, backgroundColor: 'red', - opacity: this.getTweeningValue('opacity')}} /> - - - ) - } -} - -reactMixin.onClass(App, tweenState.Mixin); -``` -[Run this example](https://rnplay.org/apps/4FUQ-A) - -![](img/TweenState.gif) - -Here we animated the opacity, but as you might guess, we can animate any -numeric value. Read more about react-tween-state in its -[README](https://github.com/chenglou/react-tween-state). - -### Rebound (Not recommended - use [Animated](docs/animations.html#animated) instead) - -[Rebound.js](https://github.com/facebook/rebound-js) is a JavaScript port of -[Rebound for Android](https://github.com/facebook/rebound). It is -similar in concept to react-tween-state: you have an initial value and -set an end value, then Rebound generates intermediate values that you can -use for your animation. Rebound is modeled after spring physics; we -don't provide a duration when animating with springs, it is -calculated for us depending on the spring tension, friction, current -value and end value. Rebound [is used -internally](https://github.com/facebook/react-native/search?utf8=%E2%9C%93&q=rebound) -by React Native on `Navigator` and `WarningBox`. - -![](img/ReboundImage.gif) - -Notice that Rebound animations can be interrupted - if you release in -the middle of a press, it will animate back from the current state to -the original value. - -```javascript -import rebound from 'rebound'; - -class App extends React.Component { - constructor(props) { - super(props); - this._onPressIn = this._onPressIn.bind(this); - this._onPressOut = this._onPressOut.bind(this); - } - // First we initialize the spring and add a listener, which calls - // setState whenever it updates - componentWillMount() { - // Initialize the spring that will drive animations - this.springSystem = new rebound.SpringSystem(); - this._scrollSpring = this.springSystem.createSpring(); - var springConfig = this._scrollSpring.getSpringConfig(); - springConfig.tension = 230; - springConfig.friction = 10; - - this._scrollSpring.addListener({ - onSpringUpdate: () => { - this.setState({scale: this._scrollSpring.getCurrentValue()}); - }, - }); - - // Initialize the spring value at 1 - this._scrollSpring.setCurrentValue(1); - } - - _onPressIn() { - this._scrollSpring.setEndValue(0.5); - } - - _onPressOut() { - this._scrollSpring.setEndValue(1); - } - - render() { - var imageStyle = { - width: 250, - height: 200, - transform: [{scaleX: this.state.scale}, {scaleY: this.state.scale}], - }; - - var imageUri = "img/ReboundExample.png"; - - return ( - - - - - - ); - } -} -``` -[Run this example](https://rnplay.org/apps/NNI5eA) - -You can also clamp the spring values so that they don't overshoot and -oscillate around the end value. In the above example, we would add -`this._scrollSpring.setOvershootClampingEnabled(true)` to change this. -See the below gif for an example of where in your interface you might -use this. - -![](img/Rebound.gif) Screenshot from -[react-native-scrollable-tab-view](https://github.com/brentvatne/react-native-scrollable-tab-view). -You can run a similar example [here](https://rnplay.org/apps/qHU_5w). - -#### A sidenote about setNativeProps +### `setNativeProps` As mentioned [in the Direction Manipulation section](docs/direct-manipulation.html), `setNativeProps` allows us to modify properties of native-backed @@ -545,43 +499,3 @@ using the [InteractionManager](docs/interactionmanager.html). You can monitor the frame rate by using the In-App Developer Menu "FPS Monitor" tool. - -### Navigator Scene Transitions - -As mentioned in the [Navigator -Comparison](docs/navigator-comparison.html#content), -`Navigator` is implemented in JavaScript and `NavigatorIOS` is a wrapper -around native functionality provided by `UINavigationController`, so -these scene transitions apply only to `Navigator`. In order to re-create -the various animations provided by `UINavigationController` and also -make them customizable, React Native exposes a -[NavigatorSceneConfigs](https://github.com/facebook/react-native/blob/master/Libraries/CustomComponents/Navigator/NavigatorSceneConfigs.js) API which is then handed over to the [Navigator](https://github.com/facebook/react-native/blob/master/Libraries/CustomComponents/Navigator/Navigator.js) `configureScene` prop. - -```javascript -import { Dimensions } from 'react-native'; -var SCREEN_WIDTH = Dimensions.get('window').width; -var BaseConfig = Navigator.SceneConfigs.FloatFromRight; - -var CustomLeftToRightGesture = Object.assign({}, BaseConfig.gestures.pop, { - // Make it snap back really quickly after canceling pop - snapVelocity: 8, - - // Make it so we can drag anywhere on the screen - edgeHitWidth: SCREEN_WIDTH, -}); - -var CustomSceneConfig = Object.assign({}, BaseConfig, { - // A very tightly wound spring will make this transition fast - springTension: 100, - springFriction: 1, - - // Use our custom gesture defined above - gestures: { - pop: CustomLeftToRightGesture, - } -}); -``` -[Run this example](https://rnplay.org/apps/HPy6UA) - -For further information about customizing scene transitions, [read the -source](https://github.com/facebook/react-native/blob/master/Libraries/CustomComponents/Navigator/NavigatorSceneConfigs.js). diff --git a/website/src/react-native/img/AnimatedFadeInView.gif b/website/src/react-native/img/AnimatedFadeInView.gif new file mode 100644 index 0000000000000000000000000000000000000000..d0d02a1a2ab918607c106c622f3366774ddca146 GIT binary patch literal 44686 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