diff --git a/packages/animations/src/animation_builder.ts b/packages/animations/src/animation_builder.ts index ba6c6ec2ac..5d8d826d31 100644 --- a/packages/animations/src/animation_builder.ts +++ b/packages/animations/src/animation_builder.ts @@ -9,31 +9,42 @@ import {AnimationMetadata, AnimationOptions} from './animation_metadata'; import {AnimationPlayer} from './players/animation_player'; /** - * AnimationBuilder is an injectable service that is available when the {@link - * BrowserAnimationsModule BrowserAnimationsModule} or {@link NoopAnimationsModule - * NoopAnimationsModule} modules are used within an application. + * An injectable service that produces an animation sequence programmatically within an + * Angular component or directive. + * Provided by the `BrowserAnimationsModule` or `NoopAnimationsModule`. * - * The purpose of this service is to produce an animation sequence programmatically within an - * angular component or directive. + * @usageNotes * - * Programmatic animations are first built and then a player is created when the build animation is - * attached to an element. + * To use this service, add it to your component or directive as a dependency. + * The service is instantiated along with your component. + * + * Apps do not typically need to create their own animation players, but if you + * do need to, follow these steps: + * + * 1. Use the `build()` method to create a programmatic animation using the + * `animate()` function. The method returns an `AnimationFactory` instance. + * + * 2. Use the factory object to create an `AnimationPlayer` and attach it to a DOM element. + * + * 3. Use the player object to control the animation programmatically. + * + * For example: * * ```ts - * // remember to include the BrowserAnimationsModule module for this to work... + * // import the service from BrowserAnimationsModule * import {AnimationBuilder} from '@angular/animations'; - * + * // require the service as a dependency * class MyCmp { * constructor(private _builder: AnimationBuilder) {} * * makeAnimation(element: any) { - * // first build the animation + * // first define a reusable animation * const myAnimation = this._builder.build([ * style({ width: 0 }), * animate(1000, style({ width: '100px' })) * ]); * - * // then create a player from it + * // use the returned factory object to create a player * const player = myAnimation.create(element); * * player.play(); @@ -41,22 +52,29 @@ import {AnimationPlayer} from './players/animation_player'; * } * ``` * - * When an animation is built an instance of {@link AnimationFactory AnimationFactory} will be - * returned. Using that an {@link AnimationPlayer AnimationPlayer} can be created which can then be - * used to start the animation. - * - * @experimental Animation support is experimental. */ export abstract class AnimationBuilder { + /** + * Builds a factory for producing a defined animation. + * @param animation A reusable animation definition. + * @returns A factory object that can create a player for the defined animation. + * @see `animate()` + */ abstract build(animation: AnimationMetadata|AnimationMetadata[]): AnimationFactory; } /** - * An instance of `AnimationFactory` is returned from {@link AnimationBuilder#build - * AnimationBuilder.build}. + * A factory object returned from the `AnimationBuilder`.`build()` method. * - * @experimental Animation support is experimental. */ export abstract class AnimationFactory { + /** + * Creates an `AnimationPlayer` instance for the reusable animation defined by + * the `AnimationBuilder`.`build()` method that created this factory. + * Attaches the new player a DOM element. + * @param element The DOM element to which to attach the animation. + * @param options A set of options that can include a time delay and + * additional developer-defined parameters. + */ abstract create(element: any, options?: AnimationOptions): AnimationPlayer; } diff --git a/packages/animations/src/animation_event.ts b/packages/animations/src/animation_event.ts index d4df068925..36f4151edd 100644 --- a/packages/animations/src/animation_event.ts +++ b/packages/animations/src/animation_event.ts @@ -38,11 +38,33 @@ * @experimental Animation support is experimental. */ export interface AnimationEvent { + /** + * The name of the state from which the animation is triggered. + */ fromState: string; + /** + * The name of the state in which the animation completes. + */ toState: string; + /** + * The time it takes the animation to complete, in milliseconds. + */ totalTime: number; + /** + * The animation phase in which the callback was invoked, one of + * "start" or "done". + */ phaseName: string; + /** + * The element to which the animation is attached. + */ element: any; + /** + * Internal. + */ triggerName: string; + /** + * Internal. + */ disabled: boolean; } diff --git a/packages/animations/src/players/animation_group_player.ts b/packages/animations/src/players/animation_group_player.ts index ba65d89639..c1f6a40c23 100644 --- a/packages/animations/src/players/animation_group_player.ts +++ b/packages/animations/src/players/animation_group_player.ts @@ -9,6 +9,14 @@ import {scheduleMicroTask} from '../util'; import {AnimationPlayer} from './animation_player'; +/** + * A programmatic controller for a group of reusable animations. + * Used internally to control animations. + * + * @see `AnimationPlayer` + * @see `{@link animations/group group()}` + * + */ export class AnimationGroupPlayer implements AnimationPlayer { private _onDoneFns: Function[] = []; private _onStartFns: Function[] = []; diff --git a/packages/animations/src/players/animation_player.ts b/packages/animations/src/players/animation_player.ts index f3c73015ff..3813a9a44f 100644 --- a/packages/animations/src/players/animation_player.ts +++ b/packages/animations/src/players/animation_player.ts @@ -8,37 +8,110 @@ import {scheduleMicroTask} from '../util'; /** - * AnimationPlayer controls an animation sequence that was produced from a programmatic animation. - * (see {@link AnimationBuilder AnimationBuilder} for more information on how to create programmatic - * animations.) + * Provides programmatic control of a reusable animation sequence, + * built using the `build()` method of `AnimationBuilder`. The `build()` method + * returns a factory, whose `create()` method instantiates and initializes this interface. + * + * @see `AnimationBuilder` + * @see `AnimationFactory` + * @see `animate()` * - * @experimental Animation support is experimental. */ export interface AnimationPlayer { + /** + * Provides a callback to invoke when the animation finishes. + * @param fn The callback function. + * @see `finish()` + */ onDone(fn: () => void): void; + /** + * Provides a callback to invoke when the animation starts. + * @param fn The callback function. + * @see `run()` + */ onStart(fn: () => void): void; + /** + * Provides a callback to invoke after the animation is destroyed. + * @param fn The callback function. + * @see `destroy()` + * @see `beforeDestroy()` + */ onDestroy(fn: () => void): void; + /** + * Initializes the animation. + */ init(): void; + /** + * Reports whether the animation has started. + * @returns True if the animation has started, false otherwise. + */ hasStarted(): boolean; + /** + * Runs the animation, invoking the `onStart()` callback. + */ play(): void; + /** + * Pauses the animation. + */ pause(): void; + /** + * Restarts the paused animation. + */ restart(): void; + /** + * Ends the animation, invoking the `onDone()` callback. + */ finish(): void; + /** + * Destroys the animation, after invoking the `beforeDestroy()` callback. + * Calls the `onDestroy()` callback when destruction is completed. + */ destroy(): void; + /** + * Resets the animation to its initial state. + */ reset(): void; + /** + * Sets the position of the animation. + * @param position A 0-based offset into the duration, in milliseconds. + */ setPosition(position: any /** TODO #9100 */): void; + /** + * Reports the current position of the animation. + * @returns A 0-based offset into the duration, in milliseconds. + */ getPosition(): number; + /** + * The parent of this player, if any. + */ parentPlayer: AnimationPlayer|null; + /** + * The total run time of the animation, in milliseconds. + */ readonly totalTime: number; + /** + * Provides a callback to invoke before the animation is destroyed. + */ beforeDestroy?: () => any; - /** @internal */ + /** @internal + * Internal + */ triggerCallback?: (phaseName: string) => void; - /** @internal */ + /** @internal + * Internal + */ disabled?: boolean; } /** - * @experimental Animation support is experimental. + * An empty programmatic controller for reusable animations. + * Used internally when animations are disabled, to avoid + * checking for the null case when an animation player is expected. + * + * @see `animate()` + * @see `AnimationPlayer` + * @see `GroupPlayer` + * */ export class NoopAnimationPlayer implements AnimationPlayer { private _onDoneFns: Function[] = []; diff --git a/tools/public_api_guard/animations/animations.d.ts b/tools/public_api_guard/animations/animations.d.ts index 3b99955968..32965de7d6 100644 --- a/tools/public_api_guard/animations/animations.d.ts +++ b/tools/public_api_guard/animations/animations.d.ts @@ -28,7 +28,6 @@ export interface AnimationAnimateRefMetadata extends AnimationMetadata { options: AnimationOptions | null; } -/** @experimental */ export declare abstract class AnimationBuilder { abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory; } @@ -44,7 +43,6 @@ export interface AnimationEvent { triggerName: string; } -/** @experimental */ export declare abstract class AnimationFactory { abstract create(element: any, options?: AnimationOptions): AnimationPlayer; } @@ -85,7 +83,6 @@ export declare interface AnimationOptions { }; } -/** @experimental */ export interface AnimationPlayer { beforeDestroy?: () => any; parentPlayer: AnimationPlayer | null; @@ -174,7 +171,6 @@ export declare function group(steps: AnimationMetadata[], options?: AnimationOpt export declare function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata; -/** @experimental */ export declare class NoopAnimationPlayer implements AnimationPlayer { parentPlayer: AnimationPlayer | null; readonly totalTime: number;