Angular 动画公开 API 全解析基于 angular/animations API 报告文件的元数据体系与运行时接口深度指南【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular本文以 Angular 主仓库中的 API 报告文件goldens/public-api/animations/index.api.md为主体系统拆解angular/animations包的完整公开 API 表面。这份报告由 API Extractor 自动生成专门用于锁定 Angular 对外承诺的稳定公共 API凡出现在其中的函数、接口、枚举与类均构成开发者可直接引用的契约。阅读本文后你将能够准确理解动画元数据的构建函数如animate、trigger、state、transition、各种元数据接口的字段含义、选项参数语义以及编程式动画运行时AnimationBuilder、AnimationFactory、AnimationPlayer的完整用法。这份 API 报告文件是什么goldens/public-api/目录存放着 Angular 各包的 API golden 文件它们是公开 API 的黄金基线。每当包导出符号发生变化CI 都会将其与 golden 文件对比从而防止破坏性的 API 变更悄悄溜进版本。其头部注释明确了这份文件的属性Do not edit this file. It is a report generated by API Extractor.也就是说.api.md是只读产物不应手工修改若要变更 API应当修改 packages/animations 下的真实源码如 public_api.ts再由工具重新生成报告。从代码组织看angular/animations的公开入口全部由 packages/animations/public_api.ts 导出export * from ./src/animations而 src/animations.ts 再逐一汇拢各实现文件API 报告正是对这一导出树的快照。整个包的导出大致可分为四大家族元数据构建函数trigger、state、transition、animate、style、keyframes、sequence、group、query、stagger、animation、useAnimation、animateChild元数据接口AnimationTriggerMetadata、AnimationStateMetadata等 13 个Animation*Metadata类型选项与事件接口AnimationOptions、AnimationQueryOptions、AnimateChildOptions、AnimationEvent运行时编程式 APIAnimationBuilder、AnimationFactory、AnimationPlayer、NoopAnimationPlayer以及常量AUTO_STYLE与类型AnimateTimings。元数据分类的骨架AnimationMetadataType 枚举报告完整列出该枚举的 13 个取值。它是整个动画 DSL领域特定语言的类型标签每类元数据对象通过type字段标识自己属于哪一种节点枚举值数值对应构建函数 / 用途State0state()把命名状态关联到一组样式Transition1transition()描述从一个状态到另一个状态的迁移Sequence2sequence()顺序执行的步骤集合Group3group()并行执行的步骤集合Animate4animate()单个动画步时长 样式Keyframes5keyframes()带偏移量的关键帧序列Style6style()一组 CSS 属性值Trigger7trigger()可绑定到元素上的具名触发器Reference8animation()可复用动画定义AnimateChild9animateChild()执行被查询到的子动画AnimateRef10useAnimation()引用一段可复用动画Query11query()查询目标元素并对其施加动画Stagger12stagger()对查询结果逐个错峰启动在 packages/animations/src/animation_metadata.ts 中该枚举每个成员都附有对应的函数链接注释而在 packages/animations/browser/src/dsl/animation_ast_builder.ts 一类的浏览器端实现中引擎正是依据这些type值把元数据翻译成实际可播放的动画指令。所有元数据接口都继承自基础接口AnimationMetadata其唯一必需字段就是type: AnimationMetadataType。构建函数的调用形态从 trigger 到 stagger报告列出 13 个导出函数下面是它们与源码一致的确切签名和语义源码位置统一见 packages/animations/src/animation_metadata.ts。trigger声明动画触发器export function trigger(name: string, definitions: AnimationMetadata[]): AnimationTriggerMetadatatrigger是动画 DSL 的顶层容器通常在组件Component元数据的animations数组中声明内部放一组state()与transition()。模板中通过属性绑定[triggerName]expression引用它绑定值会被转换为字符串与已声明的各迁移进行前值/新值匹配。AnimationTriggerMetadata接口含name、definitions与可空的optionsparams默认值三个字段。配套两个保留状态名见state()的 JSDoc 与源码说明void表示元素脱离应用如ngIf为 false时的状态*通配符表示默认状态作为未声明状态迁移时的兜底。state状态与样式的绑定export function state( name: string, styles: AnimationStyleMetadata, options?: { params: { [name: string]: any } }, ): AnimationStateMetadata把某个状态名绑定到一组由style()生成的样式。状态一旦到达其样式会持续保留在元素上即使动画结束也不会被移除这是它与过渡动画中临时样式的关键区别。transition状态迁移表达式export function transition( stateChangeExpr: | string | ((fromState: string, toState: string, element?: any, params?: { [key: string]: any }) boolean), steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null, ): AnimationTransitionMetadata状态变化表达式State Change Expression支持多种字符串语法与函数形式fromState toState单向迁移如open closedfromState toState双向迁移如enabled disabled:enter/:leave元素进入或离开 DOM 时触发:increment/:decrement绑定数值自增/自减时触发逗号分隔的多个表达式任一匹配即触发如:increment, * enabled, :enter函数形式Angular 在每次触发器绑定值变化时调用该函数接收fromState、toState、element与params返回布尔值决定是否运行动画。几个必须记住的等价与细节void *等价于:enter* void等价于:leavetrue/false会匹配表达式的1/0但不匹配一般的 truthy/falsy 值。动画到最终状态的特殊约定若迁移的最后一步是animate()且只给时长不给样式styles 为 null则该步会被自动视为收尾弧线Angular 会自动增删 CSS 样式确保元素最终落在目标状态上。AnimationAnimateMetadata.styles的类型为AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | nullnull正对应这一场景。animate时长 样式的核心步骤export function animate( timings: string | number, styles?: AnimationStyleMetadata | AnimationKeyframesSequenceMetadata | null, ): AnimationAnimateMetadatatimings是字符串格式为duration [delay] [easing]默认时间单位为毫秒。官方源码注释给出 5 个典型写法animate(500)时长 500msanimate(1s)时长 1000msanimate(100ms 0.5s)时长 100ms、延迟 500msanimate(5s ease-in)时长 5000ms、缓动 ease-inanimate(5s 10ms cubic-bezier(.17,.67,.88,.1))时长 5000ms、延迟 10ms、自定义贝塞尔缓动。缓动关键字支持ease、ease-in、ease-out、ease-in-out或cubic-bezier()函数。样式参数既可以是一组静态目标样式style()也可以是一段关键帧keyframes()。style声明一组 CSS 样式export function style( tokens: | * | { [key: string]: string | number } | Array* | { [key: string]: string | number }, ): AnimationStyleMetadata注意三类合法取值单个键值对对象、键值对数组、以及特殊的*。*即auto-styling自动样式源码将其定义为常量AUTO_STYLE *动画开始时由 Angular 从元素当前实际样式动态取值典型用途是从 0 高度动画到元素自然高度style({ height: 0 })起步再用animate(1s, style({ height: * }))回到自然高度。keyframes精细控制时间轴export function keyframes(steps: AnimationStyleMetadata[]): AnimationKeyframesSequenceMetadata每个样式条目可通过offset属性指定应用时刻占整段动画的比例01。例如animate(5s, keyframes([ style({ backgroundColor: red, offset: 0 }), style({ backgroundColor: blue, offset: 0.2 }), style({ backgroundColor: orange, offset: 0.3 }), style({ backgroundColor: black, offset: 1 }), ]))若所有条目都省略offsetAngular 会在条目之间均匀分配。注意AnimationStyleMetadata.offset在普通style()调用中为null只有置于 keyframes 序列内时才被填充。sequence 与 group串行 vs 并行编排export function sequence(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationSequenceMetadata export function group(steps: AnimationMetadata[], options?: AnimationOptions | null): AnimationGroupMetadatasequence让内部步骤逐个执行group让内部步骤同时开始组内并行、组外等齐——无论是 sequence 还是 transition 内出现 group都要等 group 全部内步完成才继续。二者是组合动画最基础的编排原语例如入场效果常用sequence([style(...), animate(...)])属性并发变化则用group。query动画选择器export function query( selector: string, animation: AnimationMetadata | AnimationMetadata[], options?: AnimationQueryOptions | null, ): AnimationQueryMetadata在动画内查询元素并对结果施以动画。Angular 专属 token 包括query(:enter)/query(:leave)查询新插入/将移除的元素query(:animating)查询所有正在动画中的元素query(triggerName)查询带某触发器的元素query(*)查询所有带触发器的元素query(:self)把当前元素本身纳入动画序列。token 可合并为复合选择器如query(:self, .record:enter, .record:leave, subTrigger, [...])。底层使用element.querySelectorAll收集元素。官方注释特别提醒:enter/:leave真正能自主捕获的只有两类元素——通过ViewContainerRef动态插入的元素以及本质是其子集的拥有结构型指令的元素若元素的插入/移除只是父元素行为的结果应在父元素自己的:enter/:leave迁移里用其他 token 查询。例外是当父元素也正在离开时带动画触发器的元素总是可以通过:leave被查询到。stagger列表逐个错峰export function stagger( timings: string | number, animation: AnimationMetadata | AnimationMetadata[], ): AnimationStaggerMetadata配合query()使用在每个被查询条目的动画开始后间隔timings再启动下一个非常适合列表的逐条淡入/淡出。官方文档给出一个完整的可复用范例对:leave条目先stagger(100, [animate(0.5s, style({ opacity: 0 }))])对:enter条目先style({ opacity: 0 })再 stagger 淡入——由此可实现for列表增删时的流水式过渡。animation useAnimation复用动画export function animation( steps: AnimationMetadata | AnimationMetadata[], options?: AnimationOptions | null, ): AnimationReferenceMetadata export function useAnimation( animation: AnimationReferenceMetadata, options?: AnimationOptions | null, ): AnimationAnimateRefMetadataanimation()定义一段可复用动画并支持params默认参数useAnimation()在迁移内引用它并允许传入覆盖参数。官方示例var fadeAnimation animation( [ style({ opacity: {{ start }} }), animate({{ time }}, style({ opacity: {{ end }} })), ], { params: { time: 1000ms, start: 0, end: 1 } }, ); // 使用时覆盖 useAnimation(fadeAnimation, { params: { time: 2s, start: 1, end: 0 }, });模板字符串{{ param }}即参数插值语法调用方未提供的参数回落到默认值若某参数在步骤真正播放前缺失useAnimation()会抛出错误。animateChild让子动画跑起来export function animateChild(options?: AnimateChildOptions | null): AnimationAnimateChildMetadata父触发器的动画默认盖过子触发器动画父优先子被拦截。要让子动画执行父动画必须先用query()找到承载子动画的元素再以animateChild()主动播放它们。它只作用于 Angular 动画库驱动的动画CSS keyframes/transition 不在其管辖范围。它接收的AnimateChildOptions在AnimationOptions之上额外增加了duration?: number | string。选项接口delay 与 params 的语义报告集中给出了三个嵌套的选项接口。AnimationOptions是两个动画函数族transition、sequence、group、query、animation、useAnimation、animateChild以及编程式AnimationBuilder动画共用的选项基础delay?: number | string动画动作启动前的延迟默认单位毫秒默认值为 0无延迟params?: { [name: string]: any }开发者自定义参数表键值对形式{{ name }}插值会用到它们。AnimationQueryOptions extends AnimationOptions在 query 场景额外提供optional?: boolean默认false。为false时若查询不到任何元素Angular 抛出错误为true则安静跳过limit?: number限制返回结果上限取负值时从列表尾部向前截取默认不限。AnimateChildOptions extends AnimationOptions额外支持duration?: number | string用于控制子动画的时长源码见 packages/animations/src/animation_metadata.ts。AnimateTimings是解析后的时序类型三个字段与animate()字符串参数一一对应type AnimateTimings { duration: number; // 完整时长默认单位毫秒 delay: number; // 启动延迟默认单位毫秒 easing: string | null; // ease-in / ease-out / ease-in-and-out 或 cubic-bezier() };编程式动画运行时Builder → Factory → Player除了声明式 DSL报告还包含一套纯编程式动画运行时。三者协作链路为AnimationBuilder.build()产出AnimationFactory工厂再create(element, options?)生成可控制的AnimationPlayer接口注释与用法范例见 packages/animations/src/animation_builder.ts。AnimationBuilder抽象基类核心方法abstract build(animation: AnimationMetadata | AnimationMetadata[]): AnimationFactory;它是可注入服务由BrowserAnimationsModule或NoopAnimationsModule提供。官方 JSDoc 推荐三步用法先build()定义可复用动画再用返回工厂的create()绑定到 DOM 元素最后用 player 编程控制。仓库实现BrowserAnimationBuilder中build会把传入数组包成sequence()随后通过渲染器的issueAnimationCommandrenderer.setProperty(element, id:register, ...)把动画注册进动画渲染器源码见 packages/animations/src/animation_builder.ts。需要注意的前提若在未启用动画的构建中注入AnimationBuilder其构造函数会抛出运行时错误提示开发者需调用provideAnimations()或provideAnimationsAsync()开启动画支持见 animation_builder.ts。AnimationFactoryabstract create(element: any, options?: AnimationOptions): AnimationPlayer;create()接收目标 DOM 元素与可选选项内含延迟与参数返回绑定到该元素上的播放器。AnimationPlayer完整的播放控制接口报告给出了接口的全部 14 个成员每个都在源码接口中有对应注释见 packages/animations/src/players/animation_player.ts成员说明onDone(fn)/onStart(fn)/onDestroy(fn)注册动画结束 / 开始 / 销毁回调init()初始化动画hasStarted(): boolean是否已开始play()/pause()/restart()播放 / 暂停 / 重新播放finish()提前结束触发onDonedestroy()销毁先调beforeDestroy再触发onDestroyreset()复位到初始状态setPosition(position: number)/getPosition(): number设置 / 读取进度01 的小数parentPlayer: AnimationPlayer \| null父播放器引用readonly totalTime: number动画总时长毫秒beforeDestroy?: () any销毁前的钩子在浏览器端RendererAnimationPlayer通过自定义渲染器事件id:done/start/destroy与动画引擎通信animation_builder.ts播放、暂停、结束等命令均由setProperty派发给底层引擎执行。NoopAnimationPlayer禁用动画时的空实现export class NoopAnimationPlayer implements AnimationPlayer { constructor(duration?: number, delay?: number); }它完整实现AnimationPlayer接口但所有操作几乎为空。源码显示totalTime duration delayplay()内部会立刻通过queueMicrotask触发onFinishanimation_player.ts——这解释了动画被禁用时回调依然触发但耗时为零秒的行为。在动画禁用场景它充当占位播放器避免到处判空。AnimationEvent触发器回调携带的数据模板中可监听(triggerName.start)与(triggerName.done)两个阶段回调其事件对象类型即AnimationEvent源码见 packages/animations/src/animation_event.tsinterface AnimationEvent { fromState: string; // 动画触发前的状态名 toState: string; // 动画结束时的状态名 totalTime: number; // 动画完成耗时毫秒 phaseName: string; // 回调阶段start 或 done element: any; // 动画挂载的元素 triggerName: string; // 触发器名源码注释标注 Internal disabled: boolean; // 动画区域是否被禁用 }在报告文件中AnimationEvent以AnimationEvent_2的内部名称出现并重导出为公开名这是 API Extractor 为避免与 DOM 全局AnimationEvent冲突的常规处理。宿主用法示例来自源码 JSDocComponent({ host: { [myAnimationTrigger]: someExpression, (myAnimationTrigger.start): captureStartEvent($event), (myAnimationTrigger.done): captureDoneEvent($event), }, // animations: [trigger(...)] })disabled标志用于判断回调是否来自被禁用动画区域当.disabled区域乃至整个应用禁用动画时触发回调仍会触发但时长按 0ms 计且事件上disabled为true。禁用动画的三层控制报告中trigger()的注释完整说明了动画禁用机制这也是整套 API 中容易被忽视的能力局部禁用在元素上绑定[.disabled]isDisabled会同时禁用该元素及内部所有动画触发器全局禁用因为禁用具有向下传递性在顶层根组件的宿主上做HostBinding(.disabled) animationsDisabled true即可关闭整个应用的动画绕过禁用父动画若通过query()显式查询到禁用区域内的子元素仍可对其运行动画用animateChild()播放被查询到的子动画同样不受禁用影响。关于 deprecated 标记API 演进的方向报告为文件内几乎每一个符号都标注了deprecated20.2 的说明文案Useanimate.enteroranimate.leaveinstead. Intent to remove in v23。结合源码中同样出现在每个 JSDoc 顶部的该提示如 animation_metadata.ts可以确认从 v20.2 起Angular 官方已将上述整套基于trigger/state/transition的传统动画 DSL 标记为弃用推荐转向新的animate.enter()/animate.leave()一等公民 API并计划在 v23 中移除这些遗留符号。这对正在维护存量动画的开发者是一个重要信号本报告列出的所有 API 依然可用并受契约保护但新代码应评估迁移到新动画 API 的路线golden 文件的历史对比价值也正在于此——通过观察 goldens/public-api 中各版本的 diff可以清晰追踪 Angular 动画 API 的演进足迹。总结angular/animations的 API 报告文件以极高的密度浓缩了该包的全部公共契约13 个元数据构建函数 13 类元数据接口 枚举标签构成声明式动画 DSLAnimationOptions/AnimationQueryOptions/AnimateChildOptions决定延迟、参数与查询行为AnimationBuilder/AnimationFactory/AnimationPlayer/NoopAnimationPlayer构成编程式运行时链路AnimationEvent承载回调上下文deprecated标记则指向 20.2 之后的新动画 API 迁移方向。将 golden 文件与其实现源码packages/animations对照阅读是理解 Angular 动画契约层与实现层最直接的方式也便于在实际开发中精准选用 API、预判未来迁移成本。【免费下载链接】angularDeliver web apps with confidence 项目地址: https://gitcode.com/GitHub_Trending/an/angular创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考