|
1 | | -web-animations-next |
2 | | -=================== |
3 | 1 |
|
4 | | -Soon to replace web-animations-js |
| 2 | +Quick Start |
| 3 | +----------- |
5 | 4 |
|
| 5 | +To provide native Chrome Web Animation features (`Element.animate` and Playback Control) in other browsers, use `web-animations.min.js`. To explore all of the proposed Web Animations API, use `web-animations-next.min.js`. |
6 | 6 |
|
7 | | -building |
8 | | -======== |
| 7 | +What is Web Animations? |
| 8 | +----------------------- |
9 | 9 |
|
10 | | -* Install grunt: `npm install -g grunt-cli` |
11 | | -* Install dev dependencies: `npm install` |
12 | | -* Run grunt: `grunt` |
| 10 | +Web Animations is a new JavaScript API for driving animated content on the web. By unifying the animation features of SVG and CSS, Web Animations unlocks features previously only usable declaratively, and exposes powerful, high-performance animation capabilities to developers. |
13 | 11 |
|
14 | | -testing |
15 | | -======= |
| 12 | +For more details see the [W3C specification](http://w3c.github.io/web-animations/). |
16 | 13 |
|
17 | | -* Open test/runner.html |
| 14 | +What is the polyfill? |
| 15 | +--------------------- |
| 16 | + |
| 17 | +The polyfill is a JavaScript implementation of the Web Animations API. It works on modern versions of all major browsers. For more details about browser support see <https://www.polymer-project.org/resources/compatibility.html>. |
| 18 | + |
| 19 | +Getting Started |
| 20 | +--------------- |
| 21 | + |
| 22 | +Here's a simple example of an animation that scales and changes the opacity of a `<div>` over 0.5 seconds. The animation alternates producing a pulsing effect. |
| 23 | + |
| 24 | + <script src="web-animations.min.js"></script> |
| 25 | + <div class="pulse" style="width:150px;">Hello world!</div> |
| 26 | + <script> |
| 27 | + var elem = document.querySelector('.pulse'); |
| 28 | + var player = document.timeline.play(new Animation(elem, [ |
| 29 | + {opacity: 0.5, transform: "scale(0.5)"}, |
| 30 | + {opacity: 1.0, transform: "scale(1)"} |
| 31 | + ], { |
| 32 | + direction: "alternate", |
| 33 | + duration: 500, |
| 34 | + iterations: Infinity |
| 35 | + })); |
| 36 | + </script> |
| 37 | + |
| 38 | +Web Animations supports off-main-thread animations, and also allows procedural generation of animations and fine-grained control of animation playback. See <http://web-animations.github.io> for ideas and inspiration! |
| 39 | + |
| 40 | +Native Fallback |
| 41 | +--------------- |
| 42 | + |
| 43 | +When the polyfill runs on a browser that implements Element.animate and AnimationPlayer Playback |
| 44 | +Control it will detect and use the underlying native features. |
| 45 | + |
| 46 | +Different Build Targets |
| 47 | +----------------------- |
| 48 | + |
| 49 | +### web-animations.min.js |
| 50 | + |
| 51 | +Tracks the Web Animations features that are supported natively in browsers. Today that means Element.animate and Playback Control in Chrome. If you’re not sure what features you will need, start with this. |
| 52 | + |
| 53 | +### web-animations-next.min.js |
| 54 | + |
| 55 | +Contains all of web-animations.min.js plus features that are still undergoing discussion or have yet to be implemented natively. |
| 56 | + |
| 57 | +### web-animations-next-lite.min.js |
| 58 | + |
| 59 | +A cut down version of web-animations-next, it removes several lesser used property handlers and some of the larger and less used features such as matrix interpolation/decomposition. |
| 60 | + |
| 61 | +### Build Target Comparison |
| 62 | + |
| 63 | +| | web-animations | web-animations-next | web-animations-next-lite | |
| 64 | +|------------------------|:--------------:|:-------------------:|:------------------------:| |
| 65 | +|Size (gzipped) | 12.5kb | 14kb | 10.5kb | |
| 66 | +|<div style='width: 180px'>Element.animate</div>|✓|✓|✓| |
| 67 | +|<div style='width: 180px'>Timing input (easings, duration, fillMode, etc.) for animations</div>|✓|✓|✓| |
| 68 | +|<div style='width: 180px'>Playback control</div>|✓|✓|✓| |
| 69 | +|<div style='width: 180px'>Support for animating lengths, transforms and opacity</div>|✓|✓|✓| |
| 70 | +|<div style='width: 180px'>Support for Animating other CSS properties</div>|✓|✓|✗| |
| 71 | +|<div style='width: 180px'>Matrix fallback for transform animations</div>|✓|✓|✗| |
| 72 | +|<div style='width: 180px'>Animation constructor</div>|✗|✓|✓| |
| 73 | +|<div style='width: 180px'>Simple Groups</div>|✗|✓|✓| |
| 74 | +|<div style='width: 180px'>Custom Effects</div>|✗|✓|✓| |
| 75 | +|<div style='width: 180px'>Timing input (easings, duration, fillMode, etc.) for groups</div>|✗|✗*|✗| |
| 76 | +|<div style='width: 180px'>Additive animation</div>|✗|✗\*|✗| |
| 77 | +|<div style='width: 180px'>Motion path</div>|✗\*|✗\*|✗| |
| 78 | +|<div style='width: 180px'>Modifiable animation timing</div>|✗|✗\*|✗\*| |
| 79 | +|<div style='width: 180px'>Modifiable group timing</div>|✗|✗\*|✗\*| |
| 80 | +|<div style='width: 180px'>Usable inline style**</div>|✓|✓|✗| |
| 81 | + |
| 82 | +\* support is planned for these features. |
| 83 | +** see inline style caveat below. |
| 84 | + |
| 85 | +Caveats |
| 86 | +------- |
| 87 | + |
| 88 | +Some things won’t ever be faithful to the implementation due to browser and CSS API limitations. These include: |
| 89 | + |
| 90 | +### Inline Style |
| 91 | + |
| 92 | +Inline style modification is the mechanism used by the polyfill to animate properties. Both web-animations and web-animations-next incorporate a module that emulates a vanilla inline style object, so that style modification from JavaScript can still work in the presence of animations. However, to keep the size of web-animations-next-lite as small as possible, the style emulation module is not included. When using this version of the polyfill, JavaScript inline style modification will be overwritten by animations. |
| 93 | + |
| 94 | +### Prefix handling |
| 95 | + |
| 96 | +The polyfill will automatically detect the correctly prefixed name to use when writing animated properties back to the platform. Where possible, the polyfill will only accept unprefixed versions of experimental features. For example: |
| 97 | + |
| 98 | + var animation = new Animation(elem, {"transform": "translate(100px, 100px)"}, 2000); |
| 99 | + |
| 100 | +will work in all browsers that implement a conforming version of transform, but |
| 101 | + |
| 102 | + var animation = new Animation(elem, {"-webkit-transform": "translate(100px, 100px)"}, 2000); |
| 103 | + |
| 104 | +will not work anywhere. |
| 105 | + |
| 106 | +API and Specification Feedback |
| 107 | +------------------------------ |
| 108 | + |
| 109 | +File an issue on GitHub: <https://github.com/w3c/web-animations/issues/new>. |
| 110 | +Alternatively, send an email to <[email protected]> with subject line “ [web-animations ] |
| 111 | +… message topic …” ([archives](http://lists.w3.org/Archives/Public/public-fx/)). |
| 112 | + |
| 113 | +Polyfill Issues |
| 114 | +--------------- |
| 115 | + |
| 116 | +Report any issues with this implementation on GitHub: <https://github.com/web-animations/web-animations-next/issues/new>. |
| 117 | + |
| 118 | +Breaking changes |
| 119 | +---------------- |
| 120 | + |
| 121 | +When we make a potentially breaking change to the polyfill's API surface (like a rename) we'll continue supporting the old version, deprecated, for three months, and ensure that there are console warnings to indicate that a change is pending. After three months, the old version of the API surface (e.g. the old version of a function name) will be removed. If you see deprecation warnings you can't avoid it by not updating. |
| 122 | + |
| 123 | +We also announce anything that isn't a bug fix on [[email protected]](https://groups.google.com/forum/#!forum/web-animations-changes). |
0 commit comments