iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
This reverts commit 005dc8f68b9d09f2a4db46bdbfae3e05d3604818.

The PR accidently introduced a breaking change
https://github.com/angular/angular/pull/23668#discussion_r186265055
This commit is contained in:
Igor Minar 2018-05-05 08:34:25 -07:00
parent e3518967ad
commit 44095d95c9
1 changed files with 53 additions and 67 deletions
Show Stats 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,14 +256,15 @@ 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 trigger is bound to (in the form of `[@triggerName]="expression"`. the
* 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
@ -288,27 +289,22 @@ 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( * function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
* fromState: string, string]: any}): boolean {
* 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';
* } * }
@ -332,14 +328,13 @@ 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({
@ -362,17 +357,16 @@ 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';
@ -387,20 +381,19 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* } * }
* ``` * ```
* *
* **What about animations that use `query()` and `animateChild()`?** * ### What about animations that us `query()` and `animateChild()`?
* * Despite inner animations being disabled, a parent animation can {@link query query} for inner
* Despite inner animations being disabled, a parent animation can `query` for inner elements located in disabled areas of the template and still animate them as it sees fit. This is
* elements located in disabled areas of the template and still animate them as it sees fit. This is also the case for when a sub animation is queried by a parent and then later animated using {@link
* also the case for when a sub animation is queried by a parent and then later animated using animateChild animateChild}.
* 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 are disabled then the `.disabled` flag on the event will be true. animations
* are disabled then the `.disabled` flag on the event will be true.
* *
* @experimental Animation support is experimental. * @experimental Animation support is experimental.
*/ */
@ -410,8 +403,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 * animation DSL language. If this information is new, please navigate to the {@link
* {@link Component#animations component animations metadata page} to gain a better understanding of * 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
@ -419,8 +412,7 @@ 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}.
* *
* {@a usage} * ### Usage
* **Usage**
* *
* The `animate` function accepts two input parameters: `timing` and `styles`: * The `animate` function accepts two input parameters: `timing` and `styles`:
* *
@ -473,7 +465,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()`
@ -512,7 +504,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
@ -537,15 +529,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 * animation DSL language. If this information is new, please navigate to the {@link
* {@link Component#animations component animations metadata page} to gain a better understanding of * 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.
@ -558,7 +550,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.
@ -597,18 +589,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.
@ -639,14 +631,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 * animation DSL language. If this information is new, please navigate to the {@link
* {@link Component#animations component animations metadata page} to gain a better understanding * Component#animations component animations metadata page} to gain a better understanding of
* of how animations in Angular are used. * 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
@ -705,7 +697,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
@ -756,8 +748,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* <div [@myAnimationTrigger]="myStatusExp">...</div> * <div [@myAnimationTrigger]="myStatusExp">...</div>
* ``` * ```
* *
* {@a the-final-animate-call} * #### 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
@ -774,7 +765,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 `*
@ -790,8 +781,7 @@ 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`.
* *
@ -807,8 +797,7 @@ 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.
* *
@ -1017,8 +1006,7 @@ 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
@ -1062,7 +1050,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
@ -1085,8 +1073,7 @@ 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
@ -1108,8 +1095,7 @@ export function useAnimation(
* query(':self, .record:enter, .record:leave, @subTrigger', [...]) * query(':self, .record:enter, .record:leave, @subTrigger', [...])
* ``` * ```
* *
* **Demo** * ### Demo
*
* *
* ``` * ```
* @Component({ * @Component({
@ -1158,7 +1144,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