uni-app x 中 animation-name 属性完全指南：@keyframes 动画命名、Vapor 模式兼容性与跨平台实现方案

uni-app x 中 animation-name 属性完全指南keyframes 动画命名、Vapor 模式兼容性与跨平台实现方案【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南以 uni-app / uni-app x 官方文档中animation-name属性说明为骨架系统讲解该属性的语法、取值、默认值以及它在 uni-app x 六大渲染管线Android/iOS/HarmonyOS 的 VDOM 与 Vapor中的真实兼容情况同时结合本仓库源码说明 App 平台应如何用UniElement.animate()等 API 实现等效的关键帧动画。读完本文你将能正确判断在哪种平台、哪种渲染模式下可以使用 CSSanimation-name并能写出可运行、可移植的跨端动画代码。一、animation-name 是什么animation-name是 CSS 动画体系中最核心的编排属性之一。它指定一个或多个keyframesat-rule 的名称这些 at-rule 描述了要应用于元素的动画。多个keyframesat-rule 以逗号分隔的名称列表的形式指定。如果指定的名称不匹配任何keyframesat-rule则不会对任何属性进行动画处理。可以把animation-name理解为动画剧本的引用keyframes负责编写剧本在时间轴上定义关键帧处的样式而animation-name负责告诉元素去执行哪份剧本。它通常与animation-duration周期时长、animation-timing-function缓动函数、animation-delay延迟、animation-iteration-count循环次数、animation-direction方向、animation-fill-mode填充模式、animation-play-state播放状态协同工作也可以通过animation简写属性一次性声明。二、语法与取值语法animation-name: [ none | keyframes-name ]#;#表示可重复、以逗号分隔的列表写法例如animation-name: fadeIn, slideUp;。当同时声明了多个动画名称时其余动画子属性如animation-duration、animation-timing-function也会以一一对应的列表形式作用于同名动画列表项不足时按规范循环复用。keyframes-name在标准 CSS 中可以是自定义标识符identifier或string字符串形式。属性值| 名称 | 兼容性 | 描述 | | :- | :- | :- | | none | Web: 4.0Android/iOS/HarmonyOS当前版本不支持 | 一个特殊的关键字表示没有关键帧。它可用于禁用动画而不改变其他标识符的顺序或禁用级联cascade中的动画 |默认值none也就是说元素默认不会执行任何关键帧动画只有当开发者显式将animation-name设置为某个已定义的keyframes名称时动画才会生效。典型用法示例以下写法在 Web 端标准浏览器语义是完整可用的关键帧动画组合keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } } .fade-box { animation-name: fadeIn; animation-duration: 1s; animation-timing-function: ease-in-out; animation-iteration-count: infinite; }也可以使用animation简写一次性声明效果等价.fade-box { animation: fadeIn 1s ease-in-out infinite; }关于与animation-name搭配的子属性仓库中同目录文档给出了完整说明animation-duration设置动画完成一个周期所需的时间默认值0s见 docs/css/animation-duration.mdanimation-timing-function设置每个周期内动画的变化速率默认值ease等价于cubic-bezier(0.25, 0.1, 0.25, 1.0)支持linear、ease-in、ease-out、ease-in-out、cubic-bezier()、steps()及其各种变体见 docs/css/animation-timing-function.mdanimation简写属性聚合animation-name、animation-duration、animation-timing-function、animation-delay、animation-iteration-count、animation-direction、animation-fill-mode与animation-play-state八项子属性见 docs/css/animation.md。三、uni-app x 平台兼容性uni-app x 将 App 渲染划分为VDOM虚拟 DOM 自渲染与Vapor原生渲染引擎两大路线animation-name的兼容情况差异显著| Android(VDOM) | Android(Vapor) | iOS(VDOM) | iOS(Vapor) | HarmonyOS(VDOM) | HarmonyOS(Vapor) | | :- | :- | :- | :- | :- | :- | | x | 5.25 | x | 5.25 | x | 5.25 |表格中x表示当前版本不支持数字表示支持的 HBuilderX 最低版本。上表含义为animation-name在 Android/iOS/HarmonyOS 三端的Vapor 模式下自 HBuilderX 5.25 起支持而在 VDOM 模式下暂不支持。与此同时官方文档还提供了App 平台拍平flatten兼容性说明。拍平是 App 渲染优化的一种手段指将可合并的视图层拍平为更少的原生节点以提升性能该能力与 CSS 动画的兼容关系单独标注如下| Android(Vapor) | iOS(Vapor) | HarmonyOS(Vapor) | | :- | :- | :- | | x | x | x |即animation-name相关能力在 App 平台拍平场景下均显示为不支持x编写动画时需要注意该限制。关键前置条件keyframes 本身的支持情况animation-name只是引用真正定义动画内容的是keyframesat-rule。仓库中的 docs/css/common/at-rules.md 明确列出| 名称 | 兼容性 | 描述 | | :- | :- | :- | | keyframes | Web: 4.0Android(VDOM): xAndroid(Vapor): 5.25iOS(VDOM): xiOS(Vapor): 5.25HarmonyOS(VDOM): xHarmonyOS(Vapor): 5.25 | 关键帧 keyframes at-rule 规则通过在动画序列中定义关键帧或 waypoints的样式来控制 CSS 动画序列中的中间步骤。与 transition 相比关键帧 keyframes 可以控制动画序列的中间步骤 |可以看到keyframes的兼容矩阵与animation-name完全一致只有 Vapor 5.25 支持。因此在使用animation-name之前务必先确认目标平台是否支持keyframes定义。四、App 平台的关键约束CSS 关键帧动画需改用 API这是本属性在 uni-app x 中最重要的一条实践结论。虽然 Vapor 5.25 开始支持keyframes与animation-name但整体而言uni-app x App 平台尤其 VDOM 模式暂不支持通过 CSSkeyframes实现关键帧动画需要改用 API 方式。官方文档 docs/css/css_diff_web.md 第 535-537 行明确写到标准 CSS 可以使用keyframes和animation编写关键帧动画。uni-app x App 平台暂不支持通过 CSSkeyframes实现关键帧动画。需要使用 API 方式实现动画详见 UniElement 的 animate 方法。docs/css/common/at-rules.md 也补充道keyframes关键帧动画在 App 平台可以使用 API 方式实现暂不支持通过 css 方式实现。详见 UniElement 的 animate 方法。仓库中的真实实践证据loading 组件的双轨实现本仓库的 uni-loading 组件 是理解这一约束的最佳案例。该组件通过条件编译区分渲染平台/* #ifdef WEB || MP*/ .__uni-loading__ { ... animation: k-loading-spin 1.333s infinite; animation-timing-function: linear; } keyframes k-loading-spin { 0% { transform: rotate(0deg); } 100% { transform: rotate(360deg); } } /* #endif */Web / 小程序端#ifdef WEB || MP直接使用animation: k-loading-spin 1.333s infinite;简写声明animation-name隐式为k-loading-spin配合animation-timing-function: linear与animation-play-state: paused暂停态通过. __uni-loading__paused类切换实现旋转加载动画App 端APP-ANDROID || APP-IOS || APP-HARMONY模板中走native-view 原生NativeLoading通道Vapor 模式直接使用native-view通过loadingState.nativeLoading?.updateStyle(...)、updatePaused(...)等原生方法驱动动画完全绕开 CSSkeyframes。这个例子证明在 uni-app x 的跨端工程里动画代码应当按平台条件编译分流——CSSanimation-name路线留给 Web/小程序以及 Vapor 5.25 的 App 场景App 端主推原生/API 动画。App 端等效方案UniElement.animate()当需要在 App 平台实现关键帧式的连续动画时官方推荐使用UniElement的animate()方法。仓库自带的 API 演示页 src/pages/API/animate/animate.uvue 给出了完整可运行的参考代码let animation: UniAnimation | null null function startAnimate() { animation mainView!.animate([ { transform: scale(1), transformOrigin: 0px 0px }, { transform: scale(0), transformOrigin: 50px 50px }, { transform: scale(1), transformOrigin: 100px 100px } ], { duration: 5000, }) animation!.oncancel (_: UniAnimationPlaybackEvent) { uni.showToast({ title: 动画被取消了 }) } animation!.onfinish (_: UniAnimationPlaybackEvent) { uni.showToast({ title: 动画播放完成 }) } } function pauseAnimate() { animation?.pause() } function resumeAnimate() { animation?.play() } function cancelAnimate() { animation?.cancel() }关键点解读动画帧数组[{...}, {...}, {...}]在语义上等价于keyframes中的 0%、50%、100% 关键帧每帧声明transform、transformOrigin等目标样式配置对象中的duration: 5000对应animation-durationfill对应animation-fill-mode演示页中widthProperty等函数还展示了fill: forwards的用法见 src/pages/API/animate/animate.uvue播放控制play()/pause()/cancel()对应animation-play-state与动画生命周期管理onfinish/oncancel回调则提供了完成/取消事件通知该演示页还覆盖了 width、height、margin、padding、border 颜色、transform、position、opacity、background-color 等大量属性的关键帧动画可作为 App 端动画能力清单参考。五、常见问题与排查建议动画不生效先查keyframes是否已定义animation-name指定的名称如果匹配不到任何keyframesat-rule任何属性都不会被动画处理这也是none之外最容易踩的坑。请检查名称拼写、大小写与作用域。确认目标平台是否支持 CSS 关键帧动画在 uni-app x 的 App VDOM 模式下keyframes与animation-name均不支持必须改用UniElement.animate()API只有 Vapor 5.25 才支持 CSS 路线。用none而不是删除属性来禁用动画none用于禁用动画的同时不改变其他标识符的顺序也不会干扰级联中的其他动画声明适合在样式覆盖场景中使用。多动画列表注意对齐逗号分隔的多个名称会与其他动画子属性按位置一一对应列表长度不一致时会被循环补齐编写时应保持各列表语义对齐。拍平flatten兼容性限制在开启拍平的 App 场景下相关能力标注为不支持涉及动画的节点需评估是否排除拍平优化。六、参见与延伸阅读docs/css/animation.mdanimation简写属性聚合全部 8 项动画子属性docs/css/animation-duration.mdanimation-duration周期时长默认0sdocs/css/animation-timing-function.mdanimation-timing-function缓动函数默认ease含steps()系列取值详解docs/css/common/at-rules.mdkeyframes等 at-rule 的兼容性总表与说明docs/css/css_diff_web.mduni-app x CSS 与标准 CSS 的差异总览含关键帧动画差异docs/dom/unielement.mdUniElement.animate()API 文档App 端关键帧动画替代方案src/pages/API/animate/animate.uvue官方 API 动画演示页源码src/uni_modules/uni-loading/components/loading/loading.uvue跨端 loading 组件源码展示 CSS 动画与原生动画的条件编译分流实践。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考