third_party/polymer/v1_0/components-chromium/neon-animation/guides/neon-animation.md

   1 ---
   2 title: neon-animation
   3 summary: "A short guide to neon-animation and neon-animated-pages"
   4 tags: ['animation','core-animated-pages']
   5 elements: ['neon-animation','neon-animated-pages']
   6 updated: 2015-05-26
   7 ---
   8
   9 # neon-animation
  10
  11 `neon-animation` is a suite of elements and behaviors to implement pluggable animated transitions for Polymer Elements using [Web Animations](https://w3c.github.io/web-animations/).
  12
  13 *Warning: The API may change.*
  14
  15 * [A basic animatable element](#basic)
  16 * [Animation configuration](#configuration)
  17   * [Animation types](#configuration-types)
  18   * [Configuration properties](#configuration-properties)
  19   * [Using multiple animations](#configuration-multiple)
  20   * [Running animations encapsulated in children nodes](#configuration-encapsulation)
  21 * [Page transitions](#page-transitions)
  22   * [Shared element animations](#shared-element)
  23   * [Declarative page transitions](#declarative-page)
  24 * [Included animations](#animations)
  25 * [Demos](#demos)
  26
  27 <a name="basic"></a>
  28 ## A basic animatable element
  29
  30 Elements that can be animated should implement the `Polymer.NeonAnimatableBehavior` behavior, or `Polymer.NeonAnimationRunnerBehavior` if they're also responsible for running an animation.
  31
  32 ```js
  33 Polymer({
  34   is: 'my-animatable',
  35   behaviors: [
  36     Polymer.NeonAnimationRunnerBehavior
  37   ],
  38   properties: {
  39     animationConfig: {
  40       value: function() {
  41         return {
  42           // provided by neon-animation/animations/scale-down-animation.html
  43           name: 'scale-down-animation',
  44           node: this
  45         }
  46       }
  47     }
  48   },
  49   listeners: {
  50     // this event is fired when the animation finishes
  51     'neon-animation-finish': '_onNeonAnimationFinish'
  52   },
  53   animate: function() {
  54     // run scale-down-animation
  55     this.playAnimation();
  56   },
  57   _onNeonAnimationFinish: function() {
  58     console.log('animation done!');
  59   }
  60 });
  61 ```
  62
  63 [Live demo](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/doc/basic.html)
  64
  65 <a name="configuration"></a>
  66 ## Animation configuration
  67
  68 <a name="configuration-types"></a>
  69 ### Animation types
  70
  71 An element might run different animations, for example it might do something different when it enters the view and when it exits from view. You can set the `animationConfig` property to a map from an animation type to configuration.
  72
  73 ```js
  74 Polymer({
  75   is: 'my-dialog',
  76   behaviors: [
  77     Polymer.NeonAnimationRunnerBehavior
  78   ],
  79   properties: {
  80     opened: {
  81       type: Boolean
  82     },
  83     animationConfig: {
  84       value: function() {
  85         return {
  86           'entry': {
  87             // provided by neon-animation/animations/scale-up-animation.html
  88             name: 'scale-up-animation',
  89             node: this
  90           },
  91           'exit': {
  92             // provided by neon-animation-animations/fade-out-animation.html
  93             name: 'fade-out-animation',
  94             node: this
  95           }
  96         }
  97       }
  98     }
  99   },
 100   listeners: {
 101     'neon-animation-finish': '_onNeonAnimationFinish'
 102   },
 103   show: function() {
 104     this.opened = true;
 105     this.style.display = 'inline-block';
 106     // run scale-up-animation
 107     this.playAnimation('entry');
 108   },
 109   hide: function() {
 110     this.opened = false;
 111     // run fade-out-animation
 112     this.playAnimation('fade-out-animation');
 113   },
 114   _onNeonAnimationFinish: function() {
 115     if (!this.opened) {
 116       this.style.display = 'none';
 117     }
 118   }
 119 });
 120 ```
 121
 122 [Live demo](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/doc/types.html)
 123
 124 You can also use the convenience properties `entryAnimation` and `exitAnimation` to set `entry` and `exit` animations:
 125
 126 ```js
 127 properties: {
 128   entryAnimation: {
 129     value: 'scale-up-animation'
 130   },
 131   exitAnimation: {
 132     value: 'fade-out-animation'
 133   }
 134 }
 135 ```
 136
 137 <a name="configuration-properties"></a>
 138 ### Configuration properties
 139
 140 You can pass additional parameters to configure an animation in the animation configuration object.
 141 All animations should accept the following properties:
 142
 143  * `name`: The name of an animation, ie. an element implementing `Polymer.NeonAnimationBehavior`.
 144  * `node`: The target node to apply the animation to. Defaults to `this`.
 145  * `timing`: Timing properties to use in this animation. They match the [Web Animations Animation Effect Timing interface](https://w3c.github.io/web-animations/#the-animationeffecttiming-interface). The
 146  properties include the following:
 147      * `duration`: The duration of the animation in milliseconds.
 148      * `delay`: The delay before the start of the animation in milliseconds.
 149      * `easing`: A timing function for the animation. Matches the CSS timing function values.
 150
 151 Animations may define additional configuration properties and they are listed in their documentation.
 152
 153 <a name="configuration-multiple"></a>
 154 ### Using multiple animations
 155
 156 Set the animation configuration to an array to combine animations, like this:
 157
 158 ```js
 159 animationConfig: {
 160   value: function() {
 161     return {
 162       // fade-in-animation is run with a 50ms delay from slide-down-animation
 163       'entry': [{
 164         name: 'slide-down-animation',
 165         node: this
 166       }, {
 167         name: 'fade-in-animation',
 168         node: this,
 169         timing: {delay: 50}
 170       }]
 171     }
 172   }
 173 }
 174 ```
 175
 176 <a name="configuration-encapsulation"></a>
 177 ### Running animations encapsulated in children nodes
 178
 179 You can include animations in the configuration that are encapsulated in a child element that implement `Polymer.NeonAnimatableBehavior` with the `animatable` property.
 180
 181 ```js
 182 animationConfig: {
 183   value: function() {
 184     return {
 185       // run fade-in-animation on this, and the entry animation on this.$.myAnimatable
 186       'entry': [
 187         {name: 'fade-in-animation', node: this},
 188         {animatable: this.$.myAnimatable, type: 'entry'}
 189       ]
 190     }
 191   }
 192 }
 193 ```
 194
 195 <a name="page-transitions"></a>
 196 ## Page transitions
 197
 198 *The artist formerly known as `<core-animated-pages>`*
 199
 200 The `neon-animated-pages` element manages a set of pages to switch between, and runs animations between the page transitions. It implements the `Polymer.IronSelectableBehavior` behavior. Each child node should implement `Polymer.NeonAnimatableBehavior` and define the `entry` and `exit` animations. During a page transition, the `entry` animation is run on the new page and the `exit` animation is run on the old page.
 201
 202 <a name="shared-element"></a>
 203 ### Shared element animations
 204
 205 Shared element animations work on multiple nodes. For example, a "hero" animation is used during a page transition to make two elements from separate pages appear to animate as a single element. Shared element animation configurations have an `id` property that identify they belong in the same animation. Elements containing shared elements also have a `sharedElements` property defines a map from `id` to element, the element involved with the animation.
 206
 207 In the incoming page:
 208
 209 ```js
 210 properties: {
 211   animationConfig: {
 212     value: function() {
 213       return {
 214         // the incoming page defines the 'entry' animation
 215         'entry': {
 216           name: 'hero-animation',
 217           id: 'hero',
 218           toPage: this
 219         }
 220       }
 221     }
 222   },
 223   sharedElements: {
 224     value: function() {
 225       return {
 226         'hero': this.$.hero
 227       }
 228     }
 229   }
 230 }
 231 ```
 232
 233 In the outgoing page:
 234
 235 ```js
 236 properties: {
 237   animationConfig: {
 238     value: function() {
 239       return {
 240         // the outgoing page defines the 'exit' animation
 241         'exit': {
 242           name: 'hero-animation',
 243           id: 'hero',
 244           fromPage: this
 245         }
 246       }
 247     }
 248   },
 249   sharedElements: {
 250     value: function() {
 251       return {
 252         'hero': this.$.otherHero
 253       }
 254     }
 255   }
 256 }
 257 ```
 258
 259 <a name="declarative-page"></a>
 260 ### Declarative page transitions
 261
 262 For convenience, if you define the `entry-animation` and `exit-animation` attributes on `<neon-animated-pages>`, those animations will apply for all page transitions.
 263
 264 For example:
 265
 266 ```js
 267 <neon-animated-pages id="pages" class="flex" selected="[[selected]]" entry-animation="slide-from-right-animation" exit-animation="slide-left-animation">
 268   <neon-animatable>1</neon-animatable>
 269   <neon-animatable>2</neon-animatable>
 270   <neon-animatable>3</neon-animatable>
 271   <neon-animatable>4</neon-animatable>
 272   <neon-animatable>5</neon-animatable>
 273 </neon-animated-pages>
 274 ```
 275
 276 The new page will slide in from the right, and the old page slide away to the left.
 277
 278 <a name="animations"></a>
 279 ## Included animations
 280
 281 Single element animations:
 282
 283  * `fade-in-animation` Animates opacity from `0` to `1`.
 284  * `fade-out-animation` Animates opacity from `1` to `0`.
 285  * `scale-down-animation` Animates transform from `scale(1)` to `scale(0)`.
 286  * `scale-up-animation` Animates transform from `scale(0)` to `scale(1)`.
 287  * `slide-down-animation` Animates transform from `translateY(-100%)` to `none`.
 288  * `slide-up-animation` Animates transform from `none` to `translateY(-100%)`.
 289  * `slide-left-animation` Animates transform from `none` to `translateX(-100%)`;
 290  * `slide-right-animation` Animates transform from `none` to `translateX(100%)`;
 291  * `slide-from-left-animation` Animates transform from `translateX(-100%)` to `none`;
 292  * `slide-from-right-animation` Animates transform from `translateX(100%)` to `none`;
 293
 294  * `transform-animation` Animates a custom transform.
 295
 296 Note that there is a restriction that only one transform animation can be applied on the same element at a time. Use the custom `transform-animation` to combine transform properties.
 297
 298 Shared element animations
 299
 300  * `hero-animation` Animates an element such that it looks like it scales and transforms from another element.
 301  * `ripple-animation` Animates an element to full screen such that it looks like it ripples from another element.
 302
 303 Group animations
 304  * `cascaded-animation` Applys an animation to an array of elements with a delay between each.
 305
 306 <a name="demos"></a>
 307 ## Demos
 308
 309  * [Grid to full screen](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/grid/index.html)
 310  * [Animation on load](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/load/index.html)
 311  * [List item to detail](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/list/index.html) (For narrow width)
 312  * [Dots to squares](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/tiles/index.html)
 313  * [Declarative](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/declarative/index.html)