cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(animations): fix content errors (#23668)

Browse Source 
PR Close #23668
This commit is contained in:
Pete Bacon Darwin
2018-05-03 10:30:58 +01:00
committed by Igor Minar
parent 5eb9c01bb6
commit 2ed41d9e38
1 changed files with 67 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
packages/animations/src/animation_metadata.ts
View File

@ -236,8 +236,8 @@ export declare interface AnimationQueryOptions extends AnimationOptions {
* Metadata representing the entry of animations. Instances of this interface are provided via the * Metadata representing the entry of animations. Instances of this interface are provided via the
* animation DSL when the {@link stagger stagger animation function} is called. * animation DSL when the {@link stagger stagger animation function} is called.
* *
* @experimental Animation support is experimental. * @experimental Animation support is experimental.
*/ */
export interface AnimationStaggerMetadata extends AnimationMetadata { export interface AnimationStaggerMetadata extends AnimationMetadata {
timings: string|number; timings: string|number;
animation: AnimationMetadata|AnimationMetadata[]; animation: AnimationMetadata|AnimationMetadata[];
@ -256,15 +256,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* Triggers are registered within the component annotation data under the * Triggers are registered within the component annotation data under the
* {@link Component#animations animations section}. An animation trigger can be placed on an element * {@link Component#animations animations section}. An animation trigger can be placed on an element
* within a template by referencing the name of the trigger followed by the expression value that * within a template by referencing the name of the trigger followed by the expression value that
the * the trigger is bound to (in the form of `[@triggerName]="expression"`.
* trigger is bound to (in the form of `[@triggerName]="expression"`.
* *
* Animation trigger bindings strigify values and then match the previous and current values against * Animation trigger bindings strigify values and then match the previous and current values against
* any linked transitions. If a boolean value is provided into the trigger binding then it will both * any linked transitions. If a boolean value is provided into the trigger binding then it will both
* be represented as `1` or `true` and `0` or `false` for a true and false boolean values * be represented as `1` or `true` and `0` or `false` for a true and false boolean values
* respectively. * respectively.
* *
* ### Usage * **Usage**
* *
* `trigger` will create an animation trigger reference based on the provided `name` value. The * `trigger` will create an animation trigger reference based on the provided `name` value. The
* provided `animation` value is expected to be an array consisting of {@link state state} and * provided `animation` value is expected to be an array consisting of {@link state state} and
@ -289,22 +288,27 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* ``` * ```
* *
* The template associated with this component will make use of the `myAnimationTrigger` animation * The template associated with this component will make use of the `myAnimationTrigger` animation
trigger by binding to an element within its template code. * trigger by binding to an element within its template code.
* *
* ```html * ```html
* <!-- somewhere inside of my-component-tpl.html --> * <!-- somewhere inside of my-component-tpl.html -->
* <div [@myAnimationTrigger]="myStatusExp">...</div> * <div [@myAnimationTrigger]="myStatusExp">...</div>
* ``` * ```
* *
* ### Using an inline function * **Using an inline function**
*
* The `transition` animation method also supports reading an inline function which can decide * The `transition` animation method also supports reading an inline function which can decide
* if its associated animation should be run. * if its associated animation should be run.
* *
* ``` * ```
* // this method will be run each time the `myAnimationTrigger` * // this method will be run each time the `myAnimationTrigger`
* // trigger value changes... * // trigger value changes...
* function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key: * function myInlineMatcherFn(
string]: any}): boolean { * fromState: string,
* toState: string,
* element: any,
* params: {[key: string]: any}
* ): boolean {
* // notice that `element` and `params` are also available here * // notice that `element` and `params` are also available here
* return toState == 'yes-please-animate'; * return toState == 'yes-please-animate';
* } * }
@ -328,13 +332,14 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* The inline method will be run each time the trigger * The inline method will be run each time the trigger
* value changes * value changes
* *
* ## Disable Animations * **Disable Animations**
*
* A special animation control binding called `@.disabled` can be placed on an element which will * A special animation control binding called `@.disabled` can be placed on an element which will
then disable animations for any inner animation triggers situated within the element as well as * then disable animations for any inner animation triggers situated within the element as well as
any animations on the element itself. * any animations on the element itself.
* *
* When true, the `@.disabled` binding will prevent all animations from rendering. The example * When true, the `@.disabled` binding will prevent all animations from rendering. The example
below shows how to use this feature: * below shows how to use this feature:
* *
* ```ts * ```ts
* @Component({ * @Component({
@ -357,16 +362,17 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* ``` * ```
* *
* The `@childAnimation` trigger will not animate because `@.disabled` prevents it from happening * The `@childAnimation` trigger will not animate because `@.disabled` prevents it from happening
(when true). * (when true).
* *
* Note that `@.disabled` will only disable all animations (this means any animations running on * Note that `@.disabled` will only disable all animations (this means any animations running on
* the same element will also be disabled). * the same element will also be disabled).
* *
* ### Disabling Animations Application-wide * **Disabling Animations Application-wide**
*
* When an area of the template is set to have animations disabled, **all** inner components will * When an area of the template is set to have animations disabled, **all** inner components will
also have their animations disabled as well. This means that all animations for an angular * also have their animations disabled as well. This means that all animations for an angular
application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular * application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular
component. * component.
* *
* ```ts * ```ts
* import {Component, HostBinding} from '@angular/core'; * import {Component, HostBinding} from '@angular/core';
@ -381,19 +387,20 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* } * }
* ``` * ```
* *
* ### What about animations that us `query()` and `animateChild()`? * **What about animations that use `query()` and `animateChild()`?**
* Despite inner animations being disabled, a parent animation can {@link query query} for inner *
elements located in disabled areas of the template and still animate them as it sees fit. This is * Despite inner animations being disabled, a parent animation can `query` for inner
also the case for when a sub animation is queried by a parent and then later animated using {@link * elements located in disabled areas of the template and still animate them as it sees fit. This is
animateChild animateChild}. * also the case for when a sub animation is queried by a parent and then later animated using
* animateChild`.
* ### Detecting when an animation is disabled *
* **Detecting when an animation is disabled**
*
* If a region of the DOM (or the entire application) has its animations disabled, then animation * If a region of the DOM (or the entire application) has its animations disabled, then animation
* trigger callbacks will still fire just as normal (only for zero seconds). * trigger callbacks will still fire just as normal (only for zero seconds).
* *
* When a trigger callback fires it will provide an instance of an {@link AnimationEvent}. If * When a trigger callback fires it will provide an instance of an {@link AnimationEvent}. If
animations * animations are disabled then the `.disabled` flag on the event will be true.
* are disabled then the `.disabled` flag on the event will be true.
* *
* @experimental Animation support is experimental. * @experimental Animation support is experimental.
*/ */
@ -403,8 +410,8 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati
/** /**
* `animate` is an animation-specific function that is designed to be used inside of Angular's * `animate` is an animation-specific function that is designed to be used inside of Angular's
* animation DSL language. If this information is new, please navigate to the {@link * animation DSL language. If this information is new, please navigate to the
* Component#animations component animations metadata page} to gain a better understanding of * {@link Component#animations component animations metadata page} to gain a better understanding of
* how animations in Angular are used. * how animations in Angular are used.
* *
* `animate` specifies an animation step that will apply the provided `styles` data for a given * `animate` specifies an animation step that will apply the provided `styles` data for a given
@ -412,7 +419,8 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati
* to be used within {@link sequence an animation sequence}, {@link group group}, or {@link * to be used within {@link sequence an animation sequence}, {@link group group}, or {@link
* transition transition}. * transition transition}.
* *
* ### Usage * {@a usage}
* **Usage**
* *
* The `animate` function accepts two input parameters: `timing` and `styles`: * The `animate` function accepts two input parameters: `timing` and `styles`:
* *
@ -465,7 +473,7 @@ export function animate(
* transition} and it will only continue to the next instruction once all of the inner animation * transition} and it will only continue to the next instruction once all of the inner animation
* steps have completed. * steps have completed.
* *
* ### Usage * **Usage**
* *
* The `steps` data that is passed into the `group` animation function can either consist of {@link * The `steps` data that is passed into the `group` animation function can either consist of {@link
* style style} or {@link animate animate} function calls. Each call to `style()` or `animate()` * style style} or {@link animate animate} function calls. Each call to `style()` or `animate()`
@ -504,7 +512,7 @@ export function group(
* To perform animation styling in parallel with other animation steps then have a look at the * To perform animation styling in parallel with other animation steps then have a look at the
* {@link group group} animation function. * {@link group group} animation function.
* *
* ### Usage * **Usage**
* *
* The `steps` data that is passed into the `sequence` animation function can either consist of * The `steps` data that is passed into the `sequence` animation function can either consist of
* {@link style style} or {@link animate animate} function calls. A call to `style()` will apply the * {@link style style} or {@link animate animate} function calls. A call to `style()` will apply the
@ -529,15 +537,15 @@ export function sequence(steps: AnimationMetadata[], options: AnimationOptions |
/** /**
* `style` is an animation-specific function that is designed to be used inside of Angular's * `style` is an animation-specific function that is designed to be used inside of Angular's
* animation DSL language. If this information is new, please navigate to the {@link * animation DSL language. If this information is new, please navigate to the
* Component#animations component animations metadata page} to gain a better understanding of * {@link Component#animations component animations metadata page} to gain a better understanding of
* how animations in Angular are used. * how animations in Angular are used.
* *
* `style` declares a key/value object containing CSS properties/styles that can then be used for * `style` declares a key/value object containing CSS properties/styles that can then be used for
* {@link state animation states}, within an {@link sequence animation sequence}, or as styling data * {@link state animation states}, within an {@link sequence animation sequence}, or as styling data
* for both {@link animate animate} and {@link keyframes keyframes}. * for both {@link animate animate} and {@link keyframes keyframes}.
* *
* ### Usage * **Usage**
* *
* `style` takes in a key/value string map as data and expects one or more CSS property/value pairs * `style` takes in a key/value string map as data and expects one or more CSS property/value pairs
* to be defined. * to be defined.
@ -550,7 +558,7 @@ export function sequence(steps: AnimationMetadata[], options: AnimationOptions |
* style({ width: 100, height: 0 }) * style({ width: 100, height: 0 })
* ``` * ```
* *
* #### Auto-styles (using `*`) * **Auto-styles (using `*`)**
* *
* When an asterix (`*`) character is used as a value then it will be detected from the element * When an asterix (`*`) character is used as a value then it will be detected from the element
* being animated and applied as animation data when the animation starts. * being animated and applied as animation data when the animation starts.
@ -589,18 +597,18 @@ export function style(
* function. To register states to an animation trigger please have a look at the {@link trigger * function. To register states to an animation trigger please have a look at the {@link trigger
* trigger} function. * trigger} function.
* *
* #### The `void` state * **The `void` state**
* *
* The `void` state value is a reserved word that angular uses to determine when the element is not * The `void` state value is a reserved word that angular uses to determine when the element is not
* apart of the application anymore (e.g. when an `ngIf` evaluates to false then the state of the * apart of the application anymore (e.g. when an `ngIf` evaluates to false then the state of the
* associated element is void). * associated element is void).
* *
* #### The `*` (default) state * **The `*` (default) state**
* *
* The `*` state (when styled) is a fallback state that will be used if the state that is being * The `*` state (when styled) is a fallback state that will be used if the state that is being
* animated is not declared within the trigger. * animated is not declared within the trigger.
* *
* ### Usage * **Usage**
* *
* `state` will declare an animation state with its associated styles * `state` will declare an animation state with its associated styles
* within the given trigger. * within the given trigger.
@ -631,14 +639,14 @@ export function state(
/** /**
* `keyframes` is an animation-specific function that is designed to be used inside of Angular's * `keyframes` is an animation-specific function that is designed to be used inside of Angular's
* animation DSL language. If this information is new, please navigate to the {@link * animation DSL language. If this information is new, please navigate to the
* Component#animations component animations metadata page} to gain a better understanding of * {@link Component#animations component animations metadata page} to gain a better understanding
* how animations in Angular are used. * of how animations in Angular are used.
* *
* `keyframes` specifies a collection of {@link style style} entries each optionally characterized * `keyframes` specifies a collection of {@link style style} entries each optionally characterized
* by an `offset` value. * by an `offset` value.
* *
* ### Usage * **Usage**
* *
* The `keyframes` animation function is designed to be used alongside the {@link animate animate} * The `keyframes` animation function is designed to be used alongside the {@link animate animate}
* animation function. Instead of applying animations from where they are currently to their * animation function. Instead of applying animations from where they are currently to their
@ -697,7 +705,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* to animate to a state value and persist its styles then one or more {@link state animation * to animate to a state value and persist its styles then one or more {@link state animation
* states} is expected to be defined. * states} is expected to be defined.
* *
* ### Usage * **Usage**
* *
* An animation transition is kicked off the `stateChangeExpr` predicate evaluates to true based on * An animation transition is kicked off the `stateChangeExpr` predicate evaluates to true based on
* what the previous state is and what the current state has become. In other words, if a transition * what the previous state is and what the current state has become. In other words, if a transition
@ -748,7 +756,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* <div [@myAnimationTrigger]="myStatusExp">...</div> * <div [@myAnimationTrigger]="myStatusExp">...</div>
* ``` * ```
* *
* #### The final `animate` call * {@a the-final-animate-call}
* **The final `animate` call**
* *
* If the final step within the transition steps is a call to `animate()` that **only** uses a * If the final step within the transition steps is a call to `animate()` that **only** uses a
* timing value with **no style data** then it will be automatically used as the final animation arc * timing value with **no style data** then it will be automatically used as the final animation arc
@ -765,7 +774,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* ]) * ])
* ``` * ```
* *
* ### Using :enter and :leave * **Using :enter and :leave**
* *
* Given that enter (insertion) and leave (removal) animations are so common, the `transition` * Given that enter (insertion) and leave (removal) animations are so common, the `transition`
* function accepts both `:enter` and `:leave` values which are aliases for the `void => *` and `* * function accepts both `:enter` and `:leave` values which are aliases for the `void => *` and `*
@ -781,7 +790,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* ]) * ])
* ``` * ```
* *
* ### Boolean values * **Boolean values**
*
* if a trigger binding value is a boolean value then it can be matched using a transition * if a trigger binding value is a boolean value then it can be matched using a transition
* expression that compares `true` and `false` or `1` and `0`. * expression that compares `true` and `false` or `1` and `0`.
* *
@ -797,7 +807,8 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* ]) * ])
* ``` * ```
* *
* ### Using :increment and :decrement * **Using :increment and :decrement**
*
* In addition to the :enter and :leave transition aliases, the :increment and :decrement aliases * In addition to the :enter and :leave transition aliases, the :increment and :decrement aliases
* can be used to kick off a transition when a numeric value has increased or decreased in value. * can be used to kick off a transition when a numeric value has increased or decreased in value.
* *
@ -1006,7 +1017,8 @@ export function animation(
* *
* Now each of the sub animations start off with respect to the `100ms` staggering step. * Now each of the sub animations start off with respect to the `100ms` staggering step.
* *
* ## The first frame of child animations * **The first frame of child animations**
*
* When sub animations are executed using `animateChild` the animation engine will always apply the * When sub animations are executed using `animateChild` the animation engine will always apply the
* first frame of every sub animation immediately at the start of the animation sequence. This way * first frame of every sub animation immediately at the start of the animation sequence. This way
* the parent animation does not need to set any initial styling data on the sub elements before the * the parent animation does not need to set any initial styling data on the sub elements before the
@ -1050,7 +1062,7 @@ export function useAnimation(
* to the queried element (by default, an array is provided, then this will be * to the queried element (by default, an array is provided, then this will be
* treated as an animation sequence). * treated as an animation sequence).
* *
* ### Usage * **Usage**
* *
* query() is designed to collect multiple elements and works internally by using * query() is designed to collect multiple elements and works internally by using
* `element.querySelectorAll`. An additional options object can be provided which * `element.querySelectorAll`. An additional options object can be provided which
@ -1073,7 +1085,8 @@ export function useAnimation(
* ], { optional: true }) * ], { optional: true })
* ``` * ```
* *
* ### Special Selector Values * **Special Selector Values**
*
* *
* The selector value within a query can collect elements that contain angular-specific * The selector value within a query can collect elements that contain angular-specific
* characteristics * characteristics
@ -1095,7 +1108,8 @@ export function useAnimation(
* query(':self, .record:enter, .record:leave, @subTrigger', [...]) * query(':self, .record:enter, .record:leave, @subTrigger', [...])
* ``` * ```
* *
* ### Demo * **Demo**
*
* *
* ``` * ```
* @Component({ * @Component({
@ -1144,7 +1158,7 @@ export function query(
* animation DSL language. It is designed to be used inside of an animation {@link query query()} * animation DSL language. It is designed to be used inside of an animation {@link query query()}
* and works by issuing a timing gap between after each queried item is animated. * and works by issuing a timing gap between after each queried item is animated.
* *
* ### Usage * **Usage**
* *
* In the example below there is a container element that wraps a list of items stamped out * In the example below there is a container element that wraps a list of items stamped out
* by an ngFor. The container element contains an animation trigger that will later be set * by an ngFor. The container element contains an animation trigger that will later be set