diff --git a/packages/animations/src/animation_metadata.ts b/packages/animations/src/animation_metadata.ts
index 7a1d4ebf74..a46524c412 100755
--- a/packages/animations/src/animation_metadata.ts
+++ b/packages/animations/src/animation_metadata.ts
@@ -5,17 +5,36 @@
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
+
+/**
+ * Represents a set of CSS styles for use in an animation style.
+ */
export interface ɵStyleData { [key: string]: string|number; }
/**
- * Metadata representing the entry of animations. Instances of this interface are created internally
- * within the Angular animation DSL.
- *
- * @experimental Animation support is experimental.
- */
+* Represents animation-step timing parameters for an animation step.
+* @see `animate()`
+*/
export declare type AnimateTimings = {
+ /**
+ * The full duration of an animation step. A number and optional time unit,
+ * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
+ * The default unit is milliseconds.
+ */
duration: number,
+ /**
+ * The delay in applying an animation step. A number and optional time unit.
+ * The default unit is milliseconds.
+ */
delay: number,
+ /**
+ * An easing style that controls how an animations step accelerates
+ * and decelerates during its run time. An easing function such as `cubic-bezier()`,
+ * or one of the following constants:
+ * - `ease-in`
+ * - `ease-out`
+ * - `ease-in-and-out`
+ */
easing: string | null
};
@@ -33,244 +52,389 @@ export declare type AnimateTimings = {
*
* Programmatic animations built using the `AnimationBuilder` service also
* make use of `AnimationOptions`.
- *
- * @experimental Animation support is experimental.
*/
export declare interface AnimationOptions {
+ /**
+ * Sets a time-delay for initiating an animation action.
+ * A number and optional time unit, such as "1s" or "10ms" for one second
+ * and 10 milliseconds, respectively.The default unit is milliseconds.
+ * Default value is 0, meaning no delay.
+ */
delay?: number|string;
+ /**
+ * A set of developer-defined parameters that modify styling and timing
+ * when an animation action starts. An array of key-value pairs, where the provided value
+ * is used as a default.
+ */
params?: {[name: string]: any};
}
/**
- * Metadata representing the entry of animations. Instances of this interface are created internally
- * within the Angular animation DSL when {@link animateChild animateChild()} is used.
+ * Adds duration options to control animation styling and timing for a child animation.
*
- * @experimental Animation support is experimental.
+ * @see `animateChild()`
*/
export declare interface AnimateChildOptions extends AnimationOptions { duration?: number|string; }
/**
- * Metadata representing the entry of animations. Usages of this enum are created
- * each time an animation DSL function is used.
+ * @description Constants for the categories of parameters that can be defined for animations.
*
- * @experimental Animation support is experimental.
+ * A corresponding function defines a set of parameters for each category, and
+ * collects them into a corresponding `AnimationMetadata` object.
*/
export const enum AnimationMetadataType {
+ /**
+ * Associates a named animation state with a set of CSS styles.
+ * See `state()`
+ */
State = 0,
+ /**
+ * Data for a transition from one animation state to another.
+ * See `transition()`
+ */
Transition = 1,
+ /**
+ * Contains a set of animation steps.
+ * See `sequence()`
+ */
Sequence = 2,
+ /**
+ * Contains a set of animation steps.
+ * See `group()`
+ */
Group = 3,
+ /**
+ * Contains an animation step.
+ * See `animate()`
+ */
Animate = 4,
+ /**
+ * Contains a set of animation steps.
+ * See `keyframes()`
+ */
Keyframes = 5,
+ /**
+ * Contains a set of CSS property-value pairs into a named style.
+ * See `style()`
+ */
Style = 6,
+ /**
+ * Associates an animation with an entry trigger that can be attached to an element.
+ * See `trigger()`
+ */
Trigger = 7,
+ /**
+ * Contains a re-usable animation.
+ * See `animation()`
+ */
Reference = 8,
+ /**
+ * Contains data to use in executing child animations returned by a query.
+ * See `animateChild()`
+ */
AnimateChild = 9,
+ /**
+ * Contains animation parameters for a re-usable animation.
+ * See `useAnimation()`
+ */
AnimateRef = 10,
+ /**
+ * Contains child-animation query data.
+ * See `query()`
+ */
Query = 11,
+ /**
+ * Contains data for staggering an animation sequence.
+ * See `stagger()`
+ */
Stagger = 12
}
/**
- * @experimental Animation support is experimental.
+ * Specifies automatic styling.
*/
export const AUTO_STYLE = '*';
/**
- * @experimental Animation support is experimental.
+ * Base for animation data structures.
*/
export interface AnimationMetadata { type: AnimationMetadataType; }
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link trigger trigger animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Contains an animation trigger. Instantiated and returned by the
+ * `trigger()` function.
*/
export interface AnimationTriggerMetadata extends AnimationMetadata {
+ /**
+ * The trigger name, used to associate it with an element. Unique within the component.
+ */
name: string;
+ /**
+ * An animation definition object, containing an array of state and transition declarations.
+ */
definitions: AnimationMetadata[];
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: {params?: {[name: string]: any}}|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link state state animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation state by associating a state name with a set of CSS styles.
+ * Instantiated and returned by the `state()` function.
*/
export interface AnimationStateMetadata extends AnimationMetadata {
+ /**
+ * The state name, unique within the component.
+ */
name: string;
+ /**
+ * The CSS styles associated with this state.
+ */
styles: AnimationStyleMetadata;
+ /**
+ * An options object containing
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation.
+ */
options?: {params: {[name: string]: any}};
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link transition transition animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation transition. Instantiated and returned by the
+ * `transition()` function.
*/
export interface AnimationTransitionMetadata extends AnimationMetadata {
+ /**
+ * An expression that describes a state change.
+ */
expr: string|
((fromState: string, toState: string, element?: any,
params?: {[key: string]: any}) => boolean);
+ /**
+ * One or more animation objects to which this transition applies.
+ */
animation: AnimationMetadata|AnimationMetadata[];
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * @experimental Animation support is experimental.
+ * Encapsulates a reusable animation, which is a collection of individual animation steps.
+ * Instantiated and returned by the `animation()` function, and
+ * passed to the `useAnimation()` function.
*/
export interface AnimationReferenceMetadata extends AnimationMetadata {
+ /**
+ * One or more animation step objects.
+ */
animation: AnimationMetadata|AnimationMetadata[];
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * @experimental Animation support is experimental.
+ * Encapsulates an animation query. Instantiated and returned by
+ * the `query()` function.
*/
export interface AnimationQueryMetadata extends AnimationMetadata {
+ /**
+ * The CSS selector for this query.
+ */
selector: string;
+ /**
+ * One or more animation step objects.
+ */
animation: AnimationMetadata|AnimationMetadata[];
+ /**
+ * A query options object.
+ */
options: AnimationQueryOptions|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link keyframes keyframes animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a keyframes sequence. Instantiated and returned by
+ * the `keyframes()` function.
*/
export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
+ /**
+ * An array of animation styles.
+ */
steps: AnimationStyleMetadata[];
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link style style animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation style. Instantiated and returned by
+ * the `style()` function.
*/
export interface AnimationStyleMetadata extends AnimationMetadata {
+ /**
+ * A set of CSS style properties.
+ */
styles: '*'|{[key: string]: string | number}|Array<{[key: string]: string | number}|'*'>;
+ /**
+ * A percentage of the total animate time at which the style is to be applied.
+ */
offset: number|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link animate animate animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation step. Instantiated and returned by
+ * the `animate()` function.
*/
export interface AnimationAnimateMetadata extends AnimationMetadata {
+ /**
+ * The timing data for the step.
+ */
timings: string|number|AnimateTimings;
+ /**
+ * A set of styles used in the step.
+ */
styles: AnimationStyleMetadata|AnimationKeyframesSequenceMetadata|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link animateChild animateChild animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a child animation, that can be run explicitly when the parent is run.
+ * Instantiated and returned by the `animateChild` function.
*/
export interface AnimationAnimateChildMetadata extends AnimationMetadata {
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link useAnimation useAnimation animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates a reusable animation.
+ * Instantiated and returned by the `useAnimation()` function.
*/
export interface AnimationAnimateRefMetadata extends AnimationMetadata {
+ /**
+ * An animation reference object.
+ */
animation: AnimationReferenceMetadata;
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link sequence sequence animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation sequence.
+ * Instantiated and returned by the `sequence()` function.
*/
export interface AnimationSequenceMetadata extends AnimationMetadata {
+ /**
+ * An array of animation step objects.
+ */
steps: AnimationMetadata[];
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link group group animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates an animation group.
+ * Instantiated and returned by the `group()` function.
*/
export interface AnimationGroupMetadata extends AnimationMetadata {
+ /**
+ * One or more animation or style steps that form this group.
+ */
steps: AnimationMetadata[];
+ /**
+ * An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation. Default delay is 0.
+ */
options: AnimationOptions|null;
}
/**
- * Metadata representing the entry of animations. Instances of this interface are provided via the
- * animation DSL when the {@link query query animation function} is called.
- *
- * @experimental Animation support is experimental.
+ * Encapsulates animation query options.
+ * Passed to the `query()` function.
*/
export declare interface AnimationQueryOptions extends AnimationOptions {
+ /**
+ * True if this query is optional, false if it is required. Default is false.
+ * A required query throws an error if no elements are retrieved when
+ * the query is executed. An optional query does not.
+ *
+ */
optional?: boolean;
/**
- * Used to limit the total amount of results from the start of the query list.
- *
- * If a negative value is provided then the queried results will be limited from the
- * end of the query list towards the beginning (e.g. if `limit: -3` is used then the
- * final 3 (or less) queried results will be used for the animation).
+ * A maximum total number of results to return from the query.
+ * If negative, results are limited from the end of the query list towards the beginning.
+ * By default, results are not limited.
*/
limit?: number;
}
/**
- * 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.
- *
-* @experimental Animation support is experimental.
-*/
+ * Encapsulates parameters for staggering the start times of a set of animation steps.
+ * Instantiated and returned by the `stagger()` function.
+ **/
export interface AnimationStaggerMetadata extends AnimationMetadata {
+ /**
+ * The timing data for the steps.
+ */
timings: string|number;
+ /**
+ * One or more animation steps.
+ */
animation: AnimationMetadata|AnimationMetadata[];
}
/**
- * `trigger` 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 Component#animations component animations metadata page} to gain a better
- * understanding of how animations in Angular are used.
- *
- * `trigger` Creates an animation trigger which will a list of {@link state state} and
- * {@link transition transition} entries that will be evaluated when the expression
+ * Creates a named animation trigger, containing a list of `state()`
+ * and `transition()` entries to be evaluated when the expression
* bound to the trigger changes.
*
- * Triggers are registered within the component annotation data under the
- * {@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
- the
- * trigger is bound to (in the form of `[@triggerName]="expression"`.
+ * @param name An identifying string.
+ * @param definitions An animation definition object, containing an array of `state()`
+ * and `transition()` declarations.
*
- * 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
- * be represented as `1` or `true` and `0` or `false` for a true and false boolean values
- * respectively.
+ * @return An object that encapsulates the trigger data.
+ *
+ * @usageNotes
+ * Define an animation trigger in the `animations` section of `@Component` metadata.
+ * In the template, reference the trigger by name and bind it to a trigger expression that
+ * evaluates to a defined animation state, using the following format:
*
- * ### Usage
+ * `[@triggerName]="expression"`
*
- * `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
- * {@link transition transition} declarations.
+ * Animation trigger bindings convert all values to strings, and then match the
+ * previous and current values against any linked transitions.
+ * Booleans can be specified as `1` or `true` and `0` or `false`.
+ *
+ * ### Usage Example
+ *
+ * The following example creates an animation trigger reference based on the provided
+ * name value.
+ * The provided animation value is expected to be an array consisting of state and
+ * transition declarations.
*
* ```typescript
* @Component({
- * selector: 'my-component',
- * templateUrl: 'my-component-tpl.html',
+ * selector: "my-component",
+ * templateUrl: "my-component-tpl.html",
* animations: [
* trigger("myAnimationTrigger", [
* state(...),
@@ -285,8 +449,8 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* }
* ```
*
- * The template associated with this component will make use of the `myAnimationTrigger` animation
- trigger by binding to an element within its template code.
+ * The template associated with this component makes use of the defined trigger
+ * by binding to an element within its template code.
*
* ```html
*
@@ -297,9 +461,8 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* The `transition` animation method also supports reading an inline function which can decide
* if its associated animation should be run.
*
- * ```
- * // this method will be run each time the `myAnimationTrigger`
- * // trigger value changes...
+ * ```typescript
+ * // this method is run each time the `myAnimationTrigger` trigger value changes.
* function myInlineMatcherFn(fromState: string, toState: string, element: any, params: {[key:
string]: any}): boolean {
* // notice that `element` and `params` are also available here
@@ -322,18 +485,16 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* }
* ```
*
- * The inline method will be run each time the trigger
- * value changes
+ * ### Disabling Animations
+ * When true, the special animation control binding `@.disabled` binding prevents
+ * all animations from rendering.
+ * Place the `@.disabled` binding on an element to disable
+ * animations on the element itself, as well as any inner animation triggers
+ * within the element.
*
- * ## Disable Animations
- * 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
- any animations on the element itself.
+ * The following example shows how to use this feature:
*
- * When true, the `@.disabled` binding will prevent all animations from rendering. The example
- below shows how to use this feature:
- *
- * ```ts
+ * ```typescript
* @Component({
* selector: 'my-component',
* template: `
@@ -353,19 +514,16 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* }
* ```
*
- * The `@childAnimation` trigger will not animate because `@.disabled` prevents it from happening
- (when true).
+ * When `@.disabled` is true, it prevents the `@childAnimation` trigger from animating,
+ * along with any inner animations.
*
- * Note that `@.disabled` will only disable all animations (this means any animations running on
- * the same element will also be disabled).
+ * ### Disable animations application-wide
+ * When an area of the template is set to have animations disabled,
+ * **all** inner components have their animations disabled as well.
+ * This means that you can disable all animations for an app
+ * by placing a host binding set on `@.disabled` on the topmost Angular component.
*
- * ### Disabling Animations Application-wide
- * 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
- application can be disabled by placing a host binding set on `@.disabled` on the topmost Angular
- component.
- *
- * ```ts
+ * ```typescript
* import {Component, HostBinding} from '@angular/core';
*
* @Component({
@@ -378,19 +536,17 @@ export interface AnimationStaggerMetadata extends AnimationMetadata {
* }
* ```
*
- * ### What about animations that us `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
- also the case for when a sub animation is queried by a parent and then later animated using {@link
- animateChild animateChild}.
-
- * ### Detecting when an animation is disabled
- * 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).
+ * ### Overriding disablement of inner animations
+ * Despite inner animations being disabled, a parent animation can `query()`
+ * for inner elements located in disabled areas of the template and still animate
+ * them if needed. This is also the case for when a sub animation is
+ * queried by a parent and then later animated using `animateChild()`.
*
- * 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.
+ * ### Detecting when an animation is disabled
+ * If a region of the DOM (or the entire application) has its animations disabled, the animation
+ * trigger callbacks still fire, but for zero seconds. When the callback fires, it provides
+ * an instance of an `AnimationEvent`. If animations are disabled,
+ * the `.disabled` flag on the event is true.
*
* @experimental Animation support is experimental.
*/
@@ -399,49 +555,60 @@ export function trigger(name: string, definitions: AnimationMetadata[]): Animati
}
/**
- * `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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines an animation step that combines styling information with timing information.
*
- * `animate` specifies an animation step that will apply the provided `styles` data for a given
- * amount of time based on the provided `timing` expression value. Calls to `animate` are expected
- * to be used within {@link sequence an animation sequence}, {@link group group}, or {@link
- * transition transition}.
+ * @param timings Sets `AnimateTimings` for the parent animation.
+ * A string in the format "duration [delay] [easing]".
+ * - Duration and delay are expressed as a number and optional time unit,
+ * such as "1s" or "10ms" for one second and 10 milliseconds, respectively.
+ * The default unit is milliseconds.
+ * - The easing value controls how the animation accelerates and decelerates
+ * during its runtime. Value is one of `ease`, `ease-in`, `ease-out`,
+ * `ease-in-out`, or a `cubic-bezier()` function call.
+ * If not supplied, no easing is applied.
*
- * ### Usage
+ * For example, the string "1s 100ms ease-out" specifies a duration of
+ * 1000 milliseconds, and delay of 100 ms, and the "ease-out" easing style,
+ * which decelerates near the end of the duration.
+ * @param styles Sets AnimationStyles for the parent animation.
+ * A function call to either `style()` or `keyframes()`
+ * that returns a collection of CSS style entries to be applied to the parent animation.
+ * When null, uses the styles from the destination state.
+ * This is useful when describing an animation step that will complete an animation;
+ * see "Animating to the final state" in `transitions()`.
+ * @returns An object that encapsulates the animation step.
*
- * The `animate` function accepts two input parameters: `timing` and `styles`:
+ * @usageNotes
+ * Call within an animation `sequence()`, `group()`, or
+ * `transition()` call to specify an animation step
+ * that applies given style data to the parent animation for a given amount of time.
*
- * - `timing` is a string based value that can be a combination of a duration with optional delay
- * and easing values. The format for the expression breaks down to `duration delay easing`
- * (therefore a value such as `1s 100ms ease-out` will be parse itself into `duration=1000,
- * delay=100, easing=ease-out`. If a numeric value is provided then that will be used as the
- * `duration` value in millisecond form.
- * - `styles` is the style input data which can either be a call to {@link style style} or {@link
- * keyframes keyframes}. If left empty then the styles from the destination state will be collected
- * and used (this is useful when describing an animation step that will complete an animation by
- * {@link transition#the-final-animate-call animating to the final state}).
+ * ### Syntax Examples
+ * **Timing examples**
*
+ * The following examples show various `timings` specifications.
+ * - `animate(500)` : Duration is 500 milliseconds.
+ * - `animate("1s")` : Duration is 1000 milliseconds.
+ * - `animate("100ms 0.5s")` : Duration is 100 milliseconds, delay is 500 milliseconds.
+ * - `animate("5s ease-in")` : Duration is 5000 milliseconds, easing in.
+ * - `animate("5s 10ms cubic-bezier(.17,.67,.88,.1)")` : Duration is 5000 milliseconds, delay is 10
+ * milliseconds, easing according to a bezier curve.
+ *
+ * **Style examples**
+ *
+ * The following example calls `style()` to set a single CSS style.
* ```typescript
- * // various functions for specifying timing data
- * animate(500, style(...))
- * animate("1s", style(...))
- * animate("100ms 0.5s", style(...))
- * animate("5s ease", style(...))
- * animate("5s 10ms cubic-bezier(.17,.67,.88,.1)", style(...))
- *
- * // either style() of keyframes() can be used
* animate(500, style({ background: "red" }))
- * animate(500, keyframes([
+ * ```
+ * The following example calls `keyframes()` to set a CSS style
+ * to different values for successive keyframes.
+ * ```typescript
+ * animate(500, keyframes(
+ * [
* style({ background: "blue" })),
* style({ background: "red" }))
- * ])
+ * ])
* ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
*/
export function animate(
timings: string | number, styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata |
@@ -450,25 +617,15 @@ export function animate(
}
/**
- * `group` 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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
- *
- * `group` specifies a list of animation steps that are all run in parallel. Grouped animations are
- * useful when a series of styles must be animated/closed off at different starting/ending times.
- *
- * The `group` function can either be used within a {@link sequence sequence} or a {@link transition
- * transition} and it will only continue to the next instruction once all of the inner animation
- * steps have completed.
- *
- * ### Usage
- *
- * 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()`
- * within a group will be executed instantly (use {@link keyframes keyframes} or a {@link
- * animate#usage animate() with a delay value} to offset styles to be applied at a later time).
+ * @description Defines a list of animation steps to be run in parallel.
*
+ * @param steps An array of animation step objects.
+ * - When steps are defined by `style()` or `animate()`
+ * function calls, each call within the group is executed instantly.
+ * - To specify offset styles to be applied at a later time, define steps with
+ * `keyframes()`, or use `animate()` calls with a delay value.
+ * For example:
+ *
* ```typescript
* group([
* animate("1s", { background: "black" }))
@@ -476,9 +633,19 @@ export function animate(
* ])
* ```
*
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ * @param options An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation.
*
- * @experimental Animation support is experimental.
+ * @return An object that encapsulates the group data.
+ *
+ * @usageNotes
+ * Grouped animations are useful when a series of styles must be
+ * animated at different starting times and closed off at different ending times.
+ *
+ * When called within a `sequence()` or a
+ * `transition()` call, does not continue to the next
+ * instruction until all of the inner animation steps have completed.
*/
export function group(
steps: AnimationMetadata[], options: AnimationOptions | null = null): AnimationGroupMetadata {
@@ -486,27 +653,12 @@ export function group(
}
/**
- * `sequence` 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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines a list of animation steps to be run sequentially, one by one.
*
- * `sequence` Specifies a list of animation steps that are run one by one. (`sequence` is used by
- * default when an array is passed as animation data into {@link transition transition}.)
- *
- * The `sequence` function can either be used within a {@link group group} or a {@link transition
- * transition} and it will only continue to the next instruction once each of the inner animation
- * steps have completed.
- *
- * To perform animation styling in parallel with other animation steps then have a look at the
- * {@link group group} animation function.
- *
- * ### Usage
- *
- * 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
- * provided styling data immediately while a call to `animate()` will apply its styling data over a
- * given time depending on its timing data.
+ * @param steps An array of animation step objects.
+ * - Steps defined by `style()` calls apply the styling data immediately.
+ * - Steps defined by `animate()` calls apply the styling data over time
+ * as specified by the timing data.
*
* ```typescript
* sequence([
@@ -515,57 +667,65 @@ export function group(
* ])
* ```
*
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
+ * @param options An options object containing a delay and
+ * developer-defined parameters that provide styling defaults and
+ * can be overridden on invocation.
*
- * @experimental Animation support is experimental.
- */
+ * @return An object that encapsulates the sequence data.
+ *
+ * @usageNotes
+ * When you pass an array of steps to a
+ * `transition()` call, the steps run sequentially by default.
+ * Compare this to the `group()` call, which runs animation steps in parallel.
+ *
+ * When a sequence is used within a `group()` or a `transition()` call,
+ * execution continues to the next instruction only after each of the inner animation
+ * steps have completed.
+ *
+ **/
export function sequence(steps: AnimationMetadata[], options: AnimationOptions | null = null):
AnimationSequenceMetadata {
return {type: AnimationMetadataType.Sequence, steps, options};
}
/**
- * `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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Declares a key/value object containing CSS properties/styles that
+ * can then be used for an animation `state`, within an animation `sequence`,
+ * or as styling data for calls to `animate()` and `keyframes()`.
*
- * `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
- * for both {@link animate animate} and {@link keyframes keyframes}.
+ * @param tokens A set of CSS styles or HTML styles associated with an animation state.
+ * The value can be any of the following:
+ * - A key-value style pair associating a CSS property with a value.
+ * - An array of key-value style pairs.
+ * - An asterisk (*), to use auto-styling, where styles are derived from the element
+ * being animated and applied to the animation when it starts.
*
- * ### Usage
+ * Auto-styling can be used to define a state that depends on layout or other
+ * environmental factors.
*
- * `style` takes in a key/value string map as data and expects one or more CSS property/value pairs
- * to be defined.
+ * @return An object that encapsulates the style data.
*
+ * @usageNotes
+ * The following examples create animation styles that collect a set of
+ * CSS property values:
+ *
* ```typescript
- * // string values are used for css properties
+ * // string values for CSS properties
* style({ background: "red", color: "blue" })
*
- * // numerical (pixel) values are also supported
+ * // numerical pixel values
* style({ width: 100, height: 0 })
* ```
*
- * #### Auto-styles (using `*`)
+ * The following example uses auto-styling to allow a component to animate from
+ * a height of 0 up to the height of the parent 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.
- *
- * This feature proves useful for a state depending on layout and/or environment factors; in such
- * cases the styles are calculated just before the animation starts.
- *
- * ```typescript
- * // the steps below will animate from 0 to the
- * // actual height of the element
+ * ```
* style({ height: 0 }),
* animate("1s", style({ height: "*" }))
* ```
*
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ **/
export function style(
tokens: '*' | {[key: string]: string | number} |
Array<'*'|{[key: string]: string | number}>): AnimationStyleMetadata {
@@ -573,53 +733,32 @@ export function style(
}
/**
- * `state` 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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Declares an animation state within a trigger attached to an element.
*
- * `state` declares an animation state within the given trigger. When a state is active within a
- * component then its associated styles will persist on the element that the trigger is attached to
- * (even when the animation ends).
+ * @param name One or more names for the defined state in a comma-separated string.
+ * The following reserved state names can be supplied to define a style for specific use
+ * cases:
*
- * To animate between states, have a look at the animation {@link transition transition} DSL
- * function. To register states to an animation trigger please have a look at the {@link trigger
- * trigger} function.
+ * - `void` You can associate styles with this name to be used when
+ * the element is detached from the application. For example, when an `ngIf` evaluates
+ * to false, the state of the associated element is void.
+ * - `*` (asterisk) Indicates the default state. You can associate styles with this name
+ * to be used as the fallback when the state that is being animated is not declared
+ * within the trigger.
*
- * #### The `void` state
+ * @param styles A set of CSS styles associated with this state, created using the
+ * `style()` function.
+ * This set of styles persists on the element once the state has been reached.
+ * @param options Parameters that can be passed to the state when it is invoked.
+ * 0 or more key-value pairs.
+ * @return An object that encapsulates the new state data.
*
- * 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
- * associated element is void).
- *
- * #### The `*` (default) state
- *
- * 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.
- *
- * ### Usage
- *
- * `state` will declare an animation state with its associated styles
- * within the given trigger.
- *
- * - `stateNameExpr` can be one or more state names separated by commas.
- * - `styles` refers to the {@link style styling data} that will be persisted on the element once
- * the state has been reached.
- *
- * ```typescript
- * // "void" is a reserved name for a state and is used to represent
- * // the state in which an element is detached from from the application.
- * state("void", style({ height: 0 }))
- *
- * // user-defined states
- * state("closed", style({ height: 0 }))
- * state("open, visible", style({ height: "*" }))
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ * @usageNotes
+ * Use the `trigger()` function to register states to an animation trigger.
+ * Use the `transition()` function to animate between states.
+ * When a state is active within a component, its associated styles persist on the element,
+ * even when the animation ends.
+ **/
export function state(
name: string, styles: AnimationStyleMetadata,
options?: {params: {[name: string]: any}}): AnimationStateMetadata {
@@ -627,26 +766,28 @@ export function state(
}
/**
- * `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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
+ * Defines a set of animation styles, associating each style with an optional `offset` value.
*
- * `keyframes` specifies a collection of {@link style style} entries each optionally characterized
- * by an `offset` value.
+ * @param steps A set of animation styles with optional offset data.
+ * The optional `offset` value for a style specifies a percentage of the total animation
+ * time at which that style is applied.
+ * @returns An object that encapsulates the keyframes data.
+ *
+ * @usageNotes
+ * Use with the `animate()` call. Instead of applying animations
+ * from the current state
+ * to the destination state, keyframes describe how each style entry is applied and at what point
+ * within the animation arc.
+ * Compare [CSS Keyframe Animations](https://www.w3schools.com/css/css3_animations.asp).
*
* ### Usage
*
- * 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
- * destination, keyframes can describe how each style entry is applied and at what point within the
- * animation arc (much like CSS Keyframe Animations do).
- *
- * For each `style()` entry an `offset` value can be set. Doing so allows to specify at what
- * percentage of the animate time the styles will be applied.
+ * In the following example, the offset values describe
+ * when each `backgroundColor` value is applied. The color is red at the start, and changes to
+ * blue when 20% of the total time has elapsed.
*
* ```typescript
- * // the provided offset values describe when each backgroundColor value is applied.
+ * // the provided offset values
* animate("5s", keyframes([
* style({ backgroundColor: "red", offset: 0 }),
* style({ backgroundColor: "blue", offset: 0.2 }),
@@ -655,8 +796,8 @@ export function state(
* ]))
* ```
*
- * Alternatively, if there are no `offset` values used within the style entries then the offsets
- * will be calculated automatically.
+ * If there are no `offset` values specified in the style entries, the offsets
+ * are calculated automatically.
*
* ```typescript
* animate("5s", keyframes([
@@ -665,127 +806,170 @@ export function state(
* style({ backgroundColor: "orange" }) // offset = 0.66
* style({ backgroundColor: "black" }) // offset = 1
* ]))
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
+ *```
*/
export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata {
return {type: AnimationMetadataType.Keyframes, steps};
}
/**
- * `transition` 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
- * Component#animations component animations metadata page} to gain a better understanding of
- * how animations in Angular are used.
- *
- * `transition` declares the {@link sequence sequence of animation steps} that will be run when the
- * provided `stateChangeExpr` value is satisfied. The `stateChangeExpr` consists of a `state1 =>
- * state2` which consists of two known states (use an asterix (`*`) to refer to a dynamic starting
- * and/or ending state).
- *
- * A function can also be provided as the `stateChangeExpr` argument for a transition and this
- * function will be executed each time a state change occurs. If the value returned within the
- * function is true then the associated animation will be run.
- *
- * Animation transitions are placed within an {@link trigger animation trigger}. For an transition
- * to animate to a state value and persist its styles then one or more {@link state animation
- * states} is expected to be defined.
- *
- * ### Usage
- *
- * 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
- * is defined that matches the old/current state criteria then the associated animation will be
+ * Declares an animation transition as a sequence of animation steps to run when a given
+ * condition is satisfied. The condition is a Boolean expression or function that compares
+ * the previous and current animation states, and returns true if this transition should occur.
+ * When the state criteria of a defined transition are met, the associated animation is
* triggered.
*
- * ```typescript
- * // all transition/state changes are defined within an animation trigger
- * trigger("myAnimationTrigger", [
- * // if a state is defined then its styles will be persisted when the
- * // animation has fully completed itself
- * state("on", style({ background: "green" })),
- * state("off", style({ background: "grey" })),
+ * @param stateChangeExpr A Boolean expression or function that compares the previous and current
+ * animation states, and returns true if this transition should occur. Note that "true" and "false"
+ * match 1 and 0, respectively. An expression is evaluated each time a state change occurs in the
+ * animation trigger element.
+ * The animation steps run when the expression evaluates to true.
*
- * // a transition animation that will be kicked off when the state value
- * // bound to "myAnimationTrigger" changes from "on" to "off"
- * transition("on => off", animate(500)),
+ * - A state-change string takes the form "state1 => state2", where each side is a defined animation
+ * state, or an asterix (*) to refer to a dynamic start or end state.
+ * - The expression string can contain multiple comma-separated statements;
+ * for example "state1 => state2, state3 => state4".
+ * - Special values `:enter` and `:leave` initiate a transition on the entry and exit states,
+ * equivalent to "void => *" and "* => void".
+ * - Special values `:increment` and `:decrement` initiate a transition when a numeric value has
+ * increased or decreased in value.
+ * - A function is executed each time a state change occurs in the animation trigger element.
+ * The animation steps run when the function returns true.
*
- * // it is also possible to do run the same animation for both directions
- * transition("on <=> off", animate(500)),
+ * @param steps One or more animation objects, as returned by the `animate()` or
+ * `sequence()` function, that form a transformation from one state to another.
+ * A sequence is used by default when you pass an array.
+ * @param options An options object that can contain a delay value for the start of the animation,
+ * and additional developer-defined parameters. Provided values for additional parameters are used
+ * as defaults, and override values can be passed to the caller on invocation.
+ * @returns An object that encapsulates the transition data.
*
- * // or to define multiple states pairs separated by commas
- * transition("on => off, off => void", animate(500)),
+ * @usageNotes
+ * The template associated with a component binds an animation trigger to an element.
*
- * // this is a catch-all state change for when an element is inserted into
- * // the page and the destination state is unknown
- * transition("void => *", [
- * style({ opacity: 0 }),
- * animate(500)
- * ]),
- *
- * // this will capture a state change between any states
- * transition("* => *", animate("1s 0s")),
- *
- * // you can also go full out and include a function
- * transition((fromState, toState) => {
- * // when `true` then it will allow the animation below to be invoked
- * return fromState == "off" && toState == "on";
- * }, animate("1s 0s"))
- * ])
- * ```
- *
- * The template associated with this component will make use of the `myAnimationTrigger` animation
- * trigger by binding to an element within its template code.
- *
- * ```html
+ * ```HTML
*
*
...
* ```
*
- * #### The final `animate` call
- *
- * 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
- * for the element to animate itself to the final state. This involves an automatic mix of
- * adding/removing CSS styles so that the element will be in the exact state it should be for the
- * applied state to be presented correctly.
+ * All transitions are defined within an animation trigger,
+ * along with named states that the transitions change to and from.
*
+ * ```typescript
+ * trigger("myAnimationTrigger", [
+ * // define states
+ * state("on", style({ background: "green" })),
+ * state("off", style({ background: "grey" })),
+ * ...]
* ```
- * // start off by hiding the element, but make sure that it animates properly to whatever state
- * // is currently active for "myAnimationTrigger"
+ *
+ * Note that when you call the `sequence()` function within a `group()`
+ * or a `transition()` call, execution does not continue to the next instruction
+ * until each of the inner animation steps have completed.
+ *
+ * ### Syntax examples
+ *
+ * The following examples define transitions between the two defined states (and default states),
+ * using various options:
+ *
+ * ```typescript
+ * // Transition occurs when the state value
+ * // bound to "myAnimationTrigger" changes from "on" to "off"
+ * transition("on => off", animate(500))
+ * // Run the same animation for both directions
+ * transition("on <=> off", animate(500))
+ * // Define multiple state-change pairs separated by commas
+ * transition("on => off, off => void", animate(500))
+ * ```
+ *
+ * ### Special values for state-change expressions
+ *
+ * - Catch-all state change for when an element is inserted into the page and the
+ * destination state is unknown:
+ *
+ * ```typescript
* transition("void => *", [
- * style({ opacity: 0 }),
- * animate(500)
- * ])
+ * style({ opacity: 0 }),
+ * animate(500)
+ * ])
* ```
*
- * ### Using :enter and :leave
+ * - Capture a state change between any states:
*
- * 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 `*
- * => void` state changes.
+ * `transition("* => *", animate("1s 0s"))`
*
- * ```
+ * - Entry and exit transitions:
+ *
+ * ```typescript
* transition(":enter", [
* style({ opacity: 0 }),
* animate(500, style({ opacity: 1 }))
- * ]),
+ * ]),
* transition(":leave", [
* animate(500, style({ opacity: 0 }))
- * ])
+ * ])
* ```
*
- * ### Boolean values
- * 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`.
+ * - Use `:increment` and `:decrement` to initiate transitions:
+ *
+ * ```typescript
+ * transition(":increment", group([
+ * query(':enter', [
+ * style({ left: '100%' }),
+ * animate('0.5s ease-out', style('*'))
+ * ]),
+ * query(':leave', [
+ * animate('0.5s ease-out', style({ left: '-100%' }))
+ * ])
+ * ]))
+ *
+ * transition(":decrement", group([
+ * query(':enter', [
+ * style({ left: '100%' }),
+ * animate('0.5s ease-out', style('*'))
+ * ]),
+ * query(':leave', [
+ * animate('0.5s ease-out', style({ left: '-100%' }))
+ * ])
+ * ]))
+ * ```
+ *
+ * ### State-change functions
+ *
+ * Here is an example of a `fromState` specified as a state-change function that invokes an
+ * animation when true:
+ *
+ * ```typescript
+ * transition((fromState, toState) =>
+ * {
+ * return fromState == "off" && toState == "on";
+ * },
+ * animate("1s 0s"))
+ * ```
+ *
+ * ### Animating to the final state
+ *
+ * If the final step in a transition is a call to `animate()` that uses a timing value
+ * with no style data, that step is automatically considered the final animation arc,
+ * for the element to reach the final state. Angular automatically adds or removes
+ * CSS styles to ensure that the element is in the correct final state.
+ *
+ * The following example defines a transition that starts by hiding the element,
+ * then makes sure that it animates properly to whatever state is currently active for trigger:
+ *
+ * ```typescript
+ * transition("void => *", [
+ * style({ opacity: 0 }),
+ * animate(500)
+ * ])
+ * ```
+ * ### Boolean value matching
+ * If a trigger binding value is a Boolean, it can be matched using a transition expression
+ * that compares true and false or 1 and 0. For example:
*
* ```
* // in the template
*
...
- *
* // in the component metadata
* trigger('openClose', [
* state('true', style({ height: '*' })),
@@ -793,87 +977,7 @@ export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSe
* transition('false <=> true', animate(500))
* ])
* ```
- *
- * ### Using :increment and :decrement
- * 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.
- *
- * ```
- * import {group, animate, query, transition, style, trigger} from '@angular/animations';
- * import {Component} from '@angular/core';
- *
- * @Component({
- * selector: 'banner-carousel-component',
- * styles: [`
- * .banner-container {
- * position:relative;
- * height:500px;
- * overflow:hidden;
- * }
- * .banner-container > .banner {
- * position:absolute;
- * left:0;
- * top:0;
- * font-size:200px;
- * line-height:500px;
- * font-weight:bold;
- * text-align:center;
- * width:100%;
- * }
- * `],
- * template: `
- *
- *
- *
- *
- *
{{ banner }}
- *
- * `,
- * animations: [
- * trigger('bannerAnimation', [
- * transition(":increment", group([
- * query(':enter', [
- * style({ left: '100%' }),
- * animate('0.5s ease-out', style('*'))
- * ]),
- * query(':leave', [
- * animate('0.5s ease-out', style({ left: '-100%' }))
- * ])
- * ])),
- * transition(":decrement", group([
- * query(':enter', [
- * style({ left: '-100%' }),
- * animate('0.5s ease-out', style('*'))
- * ]),
- * query(':leave', [
- * animate('0.5s ease-out', style({ left: '100%' }))
- * ])
- * ]))
- * ])
- * ]
- * })
- * class BannerCarouselComponent {
- * allBanners: string[] = ['1', '2', '3', '4'];
- * selectedIndex: number = 0;
- *
- * get banners() {
- * return [this.allBanners[this.selectedIndex]];
- * }
- *
- * previous() {
- * this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
- * }
- *
- * next() {
- * this.selectedIndex = Math.min(this.selectedIndex + 1, this.allBanners.length - 1);
- * }
- * }
- * ```
- *
- * {@example core/animation/ts/dsl/animation_example.ts region='Component'}
- *
- * @experimental Animation support is experimental.
- */
+ **/
export function transition(
stateChangeExpr: string | ((fromState: string, toState: string, element?: any,
params?: {[key: string]: any}) => boolean),
@@ -883,27 +987,35 @@ export function transition(
}
/**
- * `animation` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language.
+ * Produces a reusable animation that can be invoked in another animation or sequence,
+ * by calling the `useAnimation()` function.
*
- * `var myAnimation = animation(...)` is designed to produce a reusable animation that can be later
- * invoked in another animation or sequence. Reusable animations are designed to make use of
- * animation parameters and the produced animation can be used via the `useAnimation` method.
+ * @param steps One or more animation objects, as returned by the `animate()`
+ * or `sequence()` function, that form a transformation from one state to another.
+ * A sequence is used by default when you pass an array.
+ * @param options An options object that can contain a delay value for the start of the
+ * animation, and additional developer-defined parameters.
+ * Provided values for additional parameters are used as defaults,
+ * and override values can be passed to the caller on invocation.
+ * @returns An object that encapsulates the animation data.
*
- * ```
+ * @usageNotes
+ * The following example defines a reusable animation, providing some default parameter
+ * values.
+ *
+ * ```typescript
* var fadeAnimation = animation([
* style({ opacity: '{{ start }}' }),
* animate('{{ time }}',
- * style({ opacity: '{{ end }}'}))
- * ], { params: { time: '1000ms', start: 0, end: 1 }});
+ * style({ opacity: '{{ end }}'}))
+ * ],
+ * { params: { time: '1000ms', start: 0, end: 1 }});
* ```
*
- * If parameters are attached to an animation then they act as **default parameter values**. When an
- * animation is invoked via `useAnimation` then parameter values are allowed to be passed in
- * directly. If any of the passed in parameter values are missing then the default values will be
- * used.
+ * The following invokes the defined animation with a call to `useAnimation()`,
+ * passing in override parameter values.
*
- * ```
+ * ```js
* useAnimation(fadeAnimation, {
* params: {
* time: '2s',
@@ -913,9 +1025,9 @@ export function transition(
* })
* ```
*
- * If one or more parameter values are missing before animated then an error will be thrown.
- *
- * @experimental Animation support is experimental.
+ * If any of the passed-in parameter values are missing from this call,
+ * the default values are used. If one or more parameter values are missing before a step is
+ * animated, `useAnimation()` throws an error.
*/
export function animation(
steps: AnimationMetadata | AnimationMetadata[],
@@ -924,101 +1036,21 @@ export function animation(
}
/**
- * `animateChild` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. It works by allowing a queried element to execute its own
- * animation within the animation sequence.
+ * Executes a queried inner animation element within an animation sequence.
*
- * Each time an animation is triggered in angular, the parent animation
- * will always get priority and any child animations will be blocked. In order
+ * @param options An options object that can contain a delay value for the start of the
+ * animation, and additional override values for developer-defined parameters.
+ * @return An object that encapsulates the child animation data.
+ *
+ * @usageNotes
+ * Each time an animation is triggered in Angular, the parent animation
+ * has priority and any child animations are blocked. In order
* for a child animation to run, the parent animation must query each of the elements
- * containing child animations and then allow the animations to run using `animateChild`.
+ * containing child animations, and run them using this function.
*
- * The example HTML code below shows both parent and child elements that have animation
- * triggers that will execute at the same time.
- *
- * ```html
- *
- *
- *
- *
- *
- * Hello
- *
- * one
- *
- *
- * two
- *
- *
- * three
- *
- *
- * ```
- *
- * Now when the `exp` value changes to true, only the `parentAnimation` animation will animate
- * because it has priority. However, using `query` and `animateChild` each of the inner animations
- * can also fire:
- *
- * ```ts
- * // parent-child.component.ts
- * import {trigger, transition, animate, style, query, animateChild} from '@angular/animations';
- * @Component({
- * selector: 'parent-child-component',
- * animations: [
- * trigger('parentAnimation', [
- * transition('false => true', [
- * query('header', [
- * style({ opacity: 0 }),
- * animate(500, style({ opacity: 1 }))
- * ]),
- * query('@childAnimation', [
- * animateChild()
- * ])
- * ])
- * ]),
- * trigger('childAnimation', [
- * transition('false => true', [
- * style({ opacity: 0 }),
- * animate(500, style({ opacity: 1 }))
- * ])
- * ])
- * ]
- * })
- * class ParentChildCmp {
- * exp: boolean = false;
- * }
- * ```
- *
- * In the animation code above, when the `parentAnimation` transition kicks off it first queries to
- * find the header element and fades it in. It then finds each of the sub elements that contain the
- * `@childAnimation` trigger and then allows for their animations to fire.
- *
- * This example can be further extended by using stagger:
- *
- * ```ts
- * query('@childAnimation', stagger(100, [
- * animateChild()
- * ]))
- * ```
- *
- * Now each of the sub animations start off with respect to the `100ms` staggering step.
- *
- * ## The first frame of child animations
- * 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
- * the parent animation does not need to set any initial styling data on the sub elements before the
- * sub animations kick off.
- *
- * In the example above the first frame of the `childAnimation`'s `false => true` transition
- * consists of a style of `opacity: 0`. This is applied immediately when the `parentAnimation`
- * animation transition sequence starts. Only then when the `@childAnimation` is queried and called
- * with `animateChild` will it then animate to its destination of `opacity: 1`.
- *
- * Note that this feature designed to be used alongside {@link query query()} and it will only work
- * with animations that are assigned using the Angular animation DSL (this means that CSS keyframes
- * and transitions are not handled by this API).
- *
- * @experimental Animation support is experimental.
+ * Note that this feature designed to be used with `query()` and it will only work
+ * with animations that are assigned using the Angular animation library. CSS keyframes
+ * and transitions are not handled by this API.
*/
export function animateChild(options: AnimateChildOptions | null = null):
AnimationAnimateChildMetadata {
@@ -1026,11 +1058,12 @@ export function animateChild(options: AnimateChildOptions | null = null):
}
/**
- * `useAnimation` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language. It is used to kick off a reusable animation that is created using {@link
- * animation animation()}.
+ * Starts a reusable animation that is created using the `animation()` function.
*
- * @experimental Animation support is experimental.
+ * @param animation The reusable animation to start.
+ * @param options An options object that can contain a delay value for the start of
+ * the animation, and additional override values for developer-defined parameters.
+ * @return An object that contains the animation parameters.
*/
export function useAnimation(
animation: AnimationReferenceMetadata,
@@ -1039,19 +1072,33 @@ export function useAnimation(
}
/**
- * `query` is an animation-specific function that is designed to be used inside of Angular's
- * animation DSL language.
+ * Finds one or more inner elements within the current element that is
+ * being animated within a sequence. Use with `animateChild()`.
*
- * query() is used to find one or more inner elements within the current element that is
- * being animated within the sequence. The provided animation steps are applied
- * to the queried element (by default, an array is provided, then this will be
- * treated as an animation sequence).
+ * @param selector The element to query, or a set of elements that contain Angular-specific
+ * characteristics, specified with one or more of the following tokens.
+ * - `query(":enter")` or `query(":leave")` : Query for newly inserted/removed elements.
+ * - `query(":animating")` : Query all currently animating elements.
+ * - `query("@triggerName")` : Query elements that contain an animation trigger.
+ * - `query("@*")` : Query all elements that contain an animation triggers.
+ * - `query(":self")` : Include the current element into the animation sequence.
*
- * ### Usage
+ * @param animation One or more animation steps to apply to the queried element or elements.
+ * An array is treated as an animation sequence.
+ * @param options An options object. Use the 'limit' field to limit the total number of
+ * items to collect.
+ * @return An object that encapsulates the query data.
*
- * query() is designed to collect multiple elements and works internally by using
- * `element.querySelectorAll`. An additional options object can be provided which
- * can be used to limit the total amount of items to be collected.
+ * @usageNotes
+ * Tokens can be merged into a combined query selector string. For example:
+ *
+ * ```typescript
+ * query(':self, .record:enter, .record:leave, @subTrigger', [...])
+ * ```
+ *
+ * The `query()` function collects multiple elements and works internally by using
+ * `element.querySelectorAll`. Use the `limit` field of an options object to limit
+ * the total number of items to be collected. For example:
*
* ```js
* query('div', [
@@ -1060,8 +1107,8 @@ export function useAnimation(
* ], { limit: 1 })
* ```
*
- * query(), by default, will throw an error when zero items are found. If a query
- * has the `optional` flag set to true then this error will be ignored.
+ * By default, throws an error when zero items are found. Set the
+ * `optional` flag to ignore this error. For example:
*
* ```js
* query('.some-element-that-may-not-be-there', [
@@ -1070,31 +1117,12 @@ export function useAnimation(
* ], { optional: true })
* ```
*
- * ### Special Selector Values
+ * ### Usage Example
*
- * The selector value within a query can collect elements that contain angular-specific
- * characteristics
- * using special pseudo-selectors tokens.
+ * The following example queries for inner elements and animates them
+ * individually using `animateChild()`.
*
- * These include:
- *
- * - Querying for newly inserted/removed elements using `query(":enter")`/`query(":leave")`
- * - Querying all currently animating elements using `query(":animating")`
- * - Querying elements that contain an animation trigger using `query("@triggerName")`
- * - Querying all elements that contain an animation triggers using `query("@*")`
- * - Including the current element into the animation sequence using `query(":self")`
- *
- *
- * Each of these pseudo-selector tokens can be merged together into a combined query selector
- * string:
- *
- * ```
- * query(':self, .record:enter, .record:leave, @subTrigger', [...])
- * ```
- *
- * ### Demo
- *
- * ```
+ * ```typescript
* @Component({
* selector: 'inner',
* template: `
@@ -1127,8 +1155,6 @@ export function useAnimation(
* }
* }
* ```
- *
- * @experimental Animation support is experimental.
*/
export function query(
selector: string, animation: AnimationMetadata | AnimationMetadata[],
@@ -1137,16 +1163,23 @@ export function query(
}
/**
- * `stagger` is an animation-specific function that is designed to be used inside of Angular's
- * 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.
+ * Use within an animation `query()` call to issue a timing gap after
+ * each queried item is animated.
*
- * ### Usage
+ * @param timings A delay value.
+ * @param animation One ore more animation steps.
+ * @returns An object that encapsulates the stagger data.
*
- * 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
+ * @usageNotes
+ * In the following example, a container element wraps a list of items stamped out
+ * by an `ngFor`. The container element contains an animation trigger that will later be set
* to query for each of the inner items.
*
+ * Each time items are added, the opacity fade-in animation runs,
+ * and each removed item is faded out.
+ * When either of these animations occur, the stagger effect is
+ * applied after each item's animation is started.
+ *
* ```html
*
*
@@ -1158,15 +1191,15 @@ export function query(
*
* ```
*
- * The component code for this looks as such:
+ * Here is the component code:
*
- * ```ts
+ * ```typescript
* import {trigger, transition, style, animate, query, stagger} from '@angular/animations';
* @Component({
* templateUrl: 'list.component.html',
* animations: [
* trigger('listAnimation', [
- * //...
+ * ...
* ])
* ]
* })
@@ -1183,13 +1216,13 @@ export function query(
*
* toggle() {
* this.items.length ? this.hideItems() : this.showItems();
- * }
- * }
+ * }
+ * }
* ```
*
- * And now for the animation trigger code:
+ * Here is the animation trigger code:
*
- * ```ts
+ * ```typescript
* trigger('listAnimation', [
* transition('* => *', [ // each time the binding value changes
* query(':leave', [
@@ -1206,13 +1239,6 @@ export function query(
* ])
* ])
* ```
- *
- * Now each time the items are added/removed then either the opacity
- * fade-in animation will run or each removed item will be faded out.
- * When either of these animations occur then a stagger effect will be
- * applied after each item's animation is started.
- *
- * @experimental Animation support is experimental.
*/
export function stagger(
timings: string | number,
diff --git a/tools/public_api_guard/animations/animations.d.ts b/tools/public_api_guard/animations/animations.d.ts
index 07f51a54f8..2f85467bdc 100644
--- a/tools/public_api_guard/animations/animations.d.ts
+++ b/tools/public_api_guard/animations/animations.d.ts
@@ -1,36 +1,28 @@
-/** @experimental */
export declare function animate(timings: string | number, styles?: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null): AnimationAnimateMetadata;
-/** @experimental */
export declare function animateChild(options?: AnimateChildOptions | null): AnimationAnimateChildMetadata;
-/** @experimental */
export interface AnimateChildOptions extends AnimationOptions {
duration?: number | string;
}
-/** @experimental */
export declare type AnimateTimings = {
duration: number;
delay: number;
easing: string | null;
};
-/** @experimental */
export declare function animation(steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationReferenceMetadata;
-/** @experimental */
export interface AnimationAnimateChildMetadata extends AnimationMetadata {
options: AnimationOptions | null;
}
-/** @experimental */
export interface AnimationAnimateMetadata extends AnimationMetadata {
styles: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null;
timings: string | number | AnimateTimings;
}
-/** @experimental */
export interface AnimationAnimateRefMetadata extends AnimationMetadata {
animation: AnimationReferenceMetadata;
options: AnimationOptions | null;
@@ -57,23 +49,19 @@ export declare abstract class AnimationFactory {
abstract create(element: any, options?: AnimationOptions): AnimationPlayer;
}
-/** @experimental */
export interface AnimationGroupMetadata extends AnimationMetadata {
options: AnimationOptions | null;
steps: AnimationMetadata[];
}
-/** @experimental */
export interface AnimationKeyframesSequenceMetadata extends AnimationMetadata {
steps: AnimationStyleMetadata[];
}
-/** @experimental */
export interface AnimationMetadata {
type: AnimationMetadataType;
}
-/** @experimental */
export declare const enum AnimationMetadataType {
State = 0,
Transition = 1,
@@ -90,7 +78,6 @@ export declare const enum AnimationMetadataType {
Stagger = 12,
}
-/** @experimental */
export interface AnimationOptions {
delay?: number | string;
params?: {
@@ -118,38 +105,32 @@ export interface AnimationPlayer {
setPosition(p: any): void;
}
-/** @experimental */
export interface AnimationQueryMetadata extends AnimationMetadata {
animation: AnimationMetadata | AnimationMetadata[];
options: AnimationQueryOptions | null;
selector: string;
}
-/** @experimental */
export interface AnimationQueryOptions extends AnimationOptions {
limit?: number;
optional?: boolean;
}
-/** @experimental */
export interface AnimationReferenceMetadata extends AnimationMetadata {
animation: AnimationMetadata | AnimationMetadata[];
options: AnimationOptions | null;
}
-/** @experimental */
export interface AnimationSequenceMetadata extends AnimationMetadata {
options: AnimationOptions | null;
steps: AnimationMetadata[];
}
-/** @experimental */
export interface AnimationStaggerMetadata extends AnimationMetadata {
animation: AnimationMetadata | AnimationMetadata[];
timings: string | number;
}
-/** @experimental */
export interface AnimationStateMetadata extends AnimationMetadata {
name: string;
options?: {
@@ -160,7 +141,6 @@ export interface AnimationStateMetadata extends AnimationMetadata {
styles: AnimationStyleMetadata;
}
-/** @experimental */
export interface AnimationStyleMetadata extends AnimationMetadata {
offset: number | null;
styles: '*' | {
@@ -170,7 +150,6 @@ export interface AnimationStyleMetadata extends AnimationMetadata {
} | '*'>;
}
-/** @experimental */
export interface AnimationTransitionMetadata extends AnimationMetadata {
animation: AnimationMetadata | AnimationMetadata[];
expr: string | ((fromState: string, toState: string, element?: any, params?: {
@@ -179,7 +158,6 @@ export interface AnimationTransitionMetadata extends AnimationMetadata {
options: AnimationOptions | null;
}
-/** @experimental */
export interface AnimationTriggerMetadata extends AnimationMetadata {
definitions: AnimationMetadata[];
name: string;
@@ -190,13 +168,10 @@ export interface AnimationTriggerMetadata extends AnimationMetadata {
} | null;
}
-/** @experimental */
export declare const AUTO_STYLE = "*";
-/** @experimental */
export declare function group(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationGroupMetadata;
-/** @experimental */
export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata;
/** @experimental */
@@ -219,30 +194,24 @@ export declare class NoopAnimationPlayer implements AnimationPlayer {
setPosition(p: number): void;
}
-/** @experimental */
export declare function query(selector: string, animation: AnimationMetadata | AnimationMetadata[], options?: AnimationQueryOptions | null): AnimationQueryMetadata;
-/** @experimental */
export declare function sequence(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationSequenceMetadata;
-/** @experimental */
export declare function stagger(timings: string | number, animation: AnimationMetadata | AnimationMetadata[]): AnimationStaggerMetadata;
-/** @experimental */
export declare function state(name: string, styles: AnimationStyleMetadata, options?: {
params: {
[name: string]: any;
};
}): AnimationStateMetadata;
-/** @experimental */
export declare function style(tokens: '*' | {
[key: string]: string | number;
} | Array<'*' | {
[key: string]: string | number;
}>): AnimationStyleMetadata;
-/** @experimental */
export declare function transition(stateChangeExpr: string | ((fromState: string, toState: string, element?: any, params?: {
[key: string]: any;
}) => boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null): AnimationTransitionMetadata;
@@ -250,5 +219,4 @@ export declare function transition(stateChangeExpr: string | ((fromState: string
/** @experimental */
export declare function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadata;
-/** @experimental */
export declare function useAnimation(animation: AnimationReferenceMetadata, options?: AnimationOptions | null): AnimationAnimateRefMetadata;