uni-app x 中的 CSS animation-range 属性详解滚动驱动动画的时间线附着范围【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-appanimation-range是 CSS 滚动驱动动画scroll-driven animations体系中的核心简写属性用于定义动画沿其时间线timeline的附着起点与终点即动画在时间线上从何处开始、在何处结束。在 uni-app x 的 CSS 文档体系中该属性属于 动画家族属性 的一员与animation-timeline、animation-range-start、animation-range-end配套使用。本文将基于 animation-range.md 文档完整梳理该属性的语法、全部取值语义并结合仓库文档与源码核实其在不同平台上的兼容性现状帮助你在编写 uni-app x 动画样式时准确判断可用范围、避免写出无法生效的样式。animation-range 是什么按照 docs/css/animation-range.md 的定义The animation-range CSS shorthand property is used to set the start and end of an animations attachment range along its timeline, i.e. where along the timeline an animation will start and end.也就是说普通的时间型动画time-based animation通过animation-duration决定动画跑多久而滚动驱动动画scroll-driven animation的进度由滚动位置或元素视口可见度驱动animation-range则用来限定动画沿着这条时间线从哪个进度点开始附着、到哪个进度点结束附着。它是两个独立属性的简写| 拆分属性 | 作用 | 默认值 | | :- | :- | :- | |animation-range-start| 设置动画沿时间线附着的起点|normal| |animation-range-end| 设置动画沿时间线附着的终点|normal|对应文档位于 docs/css/animation-range-start.md 与 docs/css/animation-range-end.md两处均明确默认值为normal。语法文档给出的正式语法为animation-range: [ animation-range-start animation-range-end? ]#;语法要点逗号分隔列表可一次为多个动画多个animation-name分别指定附着范围每个列表项对应一个动画每项可只写一个值同时作用于 start 与 end也可写两个值前者为animation-range-start后者为animation-range-end时间线范围名称与长度百分比组合使用时格式为timeline-range-name length-percentage?。配合的两个子属性语法分别为animation-range-start: [ normal | length-percentage | timeline-range-name length-percentage? ]#; animation-range-end: [ normal | length-percentage | timeline-range-name length-percentage? ]#;从语法结构可以推断该属性设计上同时接受关键字值normal、cover、contain、entry、exit、entry-crossing、exit-crossing用于命名视图进度时间线named view progress timeline长度/百分比如0%、100%、50px直接锚定时间线进度时间线范围名 长度/百分比先用timeline-range-name选中命名时间线中的某一段范围再在该段内用长度或百分比精确定位。属性值详解根据 animation-range.md 的属性值表格animation-range支持以下 7 个关键字值均用于配合命名视图进度时间线即animation-timeline: view()场景| 名称 | 描述 | | :- | :- | |normal| 代表时间线的起点用于animation-range-start或时间线的终点用于animation-range-end。这是默认值。 | |cover| 代表命名视图进度时间线的完整范围从主体元素首次开始进入滚动视口的视图进度可见范围0% 进度起到其完全离开该范围100% 进度止。 | |contain| 代表命名视图进度时间线中主体元素被滚动视口完全包含、或完全包含滚动视口的那一段范围。若主体元素小于滚动视口则从主体元素首次被滚动视口完全包含0% 进度到不再被完全包含100% 进度若主体元素大于滚动视口则从主体元素首次完全覆盖滚动视口0% 进度到不再完全覆盖100% 进度。 | |entry| 代表命名视图进度时间线中主体元素首次开始进入滚动视口0% 进度到完全进入滚动视口100% 进度的范围。 | |exit| 代表命名视图进度时间线中主体元素首次开始离开滚动视口0% 进度到完全离开滚动视口100% 进度的范围。 | |entry-crossing| 代表命名视图进度时间线中主体元素首次开始越过滚动视口起始边缘0% 进度到完全越过滚动视口起始边缘100% 进度的范围。 | |exit-crossing| 代表命名视图进度时间线中主体元素首次开始越过滚动视口结束边缘0% 进度到完全越过滚动视口结束边缘100% 进度的范围。 |这 7 个关键字与animation-timeline的view()时间线紧密配合。需要说明的是animation-timeline属性本身在 docs/css/animation-timeline.md 中有独立文档其取值包括none、auto、scroll()匿名滚动进度时间线与view()匿名视图进度时间线默认值为auto。各关键字对应的动画区间示意以元素在滚动视口中由进入至离开的完整过程为线索可以这样理解上述关键字的时间线划分进入前元素尚未接触视口entry-crossing区间元素跨越视口起始边缘进入一侧的边entry区间元素完全进入视口cover区间元素从刚进入可见范围到完全离开可见范围即 0%100% 全程exit区间元素完全离开视口exit-crossing区间元素跨越视口结束边缘离开一侧的边离开后元素完全不可见。contain则特殊一些它描述的是主体元素完全被视口包住或完全包住视口的状态段适合做仅在元素完整可见期间播放的效果。兼容性uni-app x 平台的现状uni-app x 平台兼容性原文档的兼容性表格如下x表示不支持| Android | iOS | HarmonyOS | | :- | :- | :- | | x | x | x |即animation-range在 uni-app x 的 Android、iOS、HarmonyOS 三大原生平台当前均不支持。App 平台拍平flatten兼容性| Android(Vapor) | iOS(Vapor) | HarmonyOS(Vapor) | | :- | :- | :- | | x | x | x |即该属性同样未被列入 App 平台 Vapor拍平渲染模式的兼容范围。这一点在 docs/css/README.md 的不支持拍平的 CSS 属性清单中可以得到印证animation-range、animation-range-end、animation-range-start以及整个animation-*动画家族animation、animation-timeline、animation-composition等在 Vapor 模式下均标记为x。从源码结构看在本仓库的src目录含src/pages/CSS各样式演示页中未检索到animation-range、animation-range-start、animation-range-end的相关实现或示例代码这与文档中三端均为 x不支持的标注是一致的。为什么文档仍收录该属性uni-app x 在 App 平台实现的是 Web CSS 的子集ucss。根据 docs/css/README.md 的说明子集并不影响开发者开发出所需的界面仅是写法上没有那么丰富。当 uni-app x 编译到 web、小程序等平台时可以支持 web 的全部 css。因此animation-range这类文档的存在价值在于一方面完整对齐 Web 标准属性清单样式清单 中列出了animation-range、animation-range-end、animation-range-start三个条目另一方面通过x标注明确告知开发者——该属性当前仅在 uni-app x 编译到 Web 平台时可用在 App 原生三端含 Vapor 模式无法生效。在 App 端书写该属性不会产生滚动驱动动画效果这一点需要在实际开发中特别留意。Web 平台的使用示例虽然 App 原生平台暂不支持但在 uni-app x 编译到 Web 平台时animation-range可配合animation-timeline: view()实现滚动驱动的进度动画。典型写法如下keyframes fade-in { from { opacity: 0; transform: translateY(30px); } to { opacity: 1; transform: translateY(0); } } .card { animation-name: fade-in; animation-timeline: view(); /* 以元素自身为视图进度时间线 */ animation-range: entry 0% entry 100%; /* 元素从开始进入视口到完全进入视口期间播放 */ }拆分写法与简写等价.card { animation-name: fade-in; animation-timeline: view(); animation-range-start: entry 0%; animation-range-end: entry 100%; }再如元素在视口中完全可见的期间持续高亮可用contain.card { animation-name: highlight; animation-timeline: view(); animation-range: contain 0% contain 100%; }提示由于 uni-app x 的 App 端采用样式不继承、仅 class 选择器、flex 布局等 ucss 子集约束详见 docs/css/README.md上述滚动驱动动画示例仅针对 Web 端有效若需跨端一致的动画效果建议使用animation家族中已获得原生支持的能力例如animation简写属性在 Android(Vapor)、iOS(Vapor)、HarmonyOS(Vapor) 中均已支持到 5.25详见 animation.md或采用基于滚动事件的业务代码驱动。相关属性与延伸阅读animation-range不是孤立属性它与下列文档构成完整的滚动驱动动画家族建议一并查阅docs/css/animation-range-start.md附着范围起点默认值normaldocs/css/animation-range-end.md附着范围终点默认值normaldocs/css/animation-timeline.md选择时间线类型none、auto、scroll()、view()默认值autodocs/css/animation-duration.md其中auto取值对滚动驱动动画有特殊含义——对于时间型动画等价于0s而对于滚动驱动动画则让动画填满整条时间线docs/css/animation.mdanimation简写属性可组合animation-name、animation-duration、animation-timing-function、animation-delay、animation-iteration-count、animation-direction、animation-fill-mode、animation-play-statedocs/css/README.mduni-app x 的 ucss 子集说明、样式重置清单与不支持拍平的 CSS 属性总表可据此判断任意 CSS 属性在各平台的可用性。总结animation-range是滚动驱动动画中控制动画沿时间线从哪开始、到哪结束的关键简写属性其 7 个关键字normal、cover、contain、entry、exit、entry-crossing、exit-crossing分别对应主体元素与滚动视口之间不同的位置关系阶段。在 uni-app x 中该属性与animation-range-start、animation-range-end目前仅面向 Web 平台Android、iOS、HarmonyOS 原生端含 Vapor 拍平模式均标注为x不支持。开发者在 App 端需要滚动驱动效果时应优先采用原生已支持的动画能力或业务层滚动监听方案并随时关注 样式清单 中该属性的兼容性更新。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考