一个底部弹层(BottomSheet)的展开动画,产品给的参数很明确:时长为 300ms,缓动 EaseInOut(等同 cubic-bezier 的 ease-in-out 曲线),位移从 translateY(100%) 到 0,同时遮罩层透明度从 0 到 1。用 ArkUI 的 Animator 实现,onFrame 里按归一化进度 val 驱动两个状态变量:sheetOffset 和 maskOpacity,一个控制容器位移,一个控制遮罩透明度。
参数逐项核对过:起始值、结束值、时长、曲线、迭代次数、播放方向都对。日志里打 onFrame 回调的时间戳,从第 0 帧到第 300ms,回调覆盖得均匀,曲线插值出来的 val 序列和用外部工具算出来的一致,偏差在亚毫秒级。
但视觉上不对。遮罩已经完全不透明了,弹层还差一点点没到位;或者反过来,弹层贴到屏幕底部了,文字还在做最后一点淡入。关闭动画更明显:容器还在往下走,里面内容已经提前消失,用户看到的是 "内容先闪一下没了,壳子才滑下去"。把时长从 300ms 拉到 500ms,现象确实 "缓解" 了一点,但没消失 ------ 只是每帧的时间变长,一帧的偏移被摊薄了,本质的错位还在。改成组件自带的 animate,把动画写在 .animate() 属性上,时序立刻对齐,肉眼看不到错位。
于是你去查时间戳精度,怀疑 onFrame 的时间基准和渲染帧的时间基准不是同一个;又怀疑 val 的插值算法在两端有偏差,加了 Math.min(1, Math.max(0, val)) 的钳位、又加了 val - epsilon 的经验补偿,在某些机型上错位变小了,换一台高刷设备,错位又变成 "慢一帧"。这个 "快一帧 / 慢一帧" 的表述本身就说明问题不在数值精度上 ------它是节拍问题,不是数值问题。
结论先给:Animator 的 onFrame 回调由它自己的驱动时钟触发,这个时钟和 ArkUI 的 UI 渲染 VSync 不是同一个时钟源,两者之间没有约定 "回调一定发生在哪一帧的边界上"。你在回调里改状态变量,标脏动作落在两次 VSync 之间的任意位置:落在 VSync 之前,这一帧就能带上新值;落在 VSync 之后,就得等下一帧。动画一跑几十帧,这个 "落点随机" 会表现为持续的一帧级抖动,而在高性能相机位移、透明度这类对连续性极敏感的动画上,一帧的偏移就足以让人眼看出 "内容比壳子快一拍"。
关键要钉死的是这条边界:Animator 是 "属性值驱动器",不是 "渲染帧驱动器"。 它保证按时间给你一串插值后的数值,不保证这些数值在正确的帧上被渲染。这两件事在 V1 的 animateTo、V2 的 .animate() 体系里是被框架统一到一条链上的,在独立 Animator 里不是。
先把时钟关系说清楚:三个时钟,一条链
ArkUI 的一个页面在跑动画时,同时有三样东西按各自的节拍前进:
表格
| 时钟 | 谁驱动 | 典型周期 | 用途 |
|---|---|---|---|
| Animator 驱动时钟 | Animator 内部定时器 |
依赖实现,可能与刷新率同频,也可能不同频 | 按时间戳算插值进度,回调 onFrame |
| UI 渲染 VSync | 系统合成器 | 60Hz / 90Hz / 120Hz,随设备与省电策略变化 | 触发 build 重执行、布局、绘制、上屏 |
| 状态标脏队列 | ArkUI 状态管理 | 事件驱动,无固定周期 | 收集被改动的状态变量,等下一帧统一处理 |
一段动画从 "数据变了" 到 "上屏" 的完整链路是:
Animator 回调(onFrame,电平:任意时刻)
│ 在回调里写状态变量
▼
状态标脏(把脏变量放进待处理集合,不立即渲染)
│ 等下一个 VSync
▼
VSync 到达 → 处理脏变量 → build 重执行 → 布局 → 绘制 → 合成上屏
如果 onFrame 的触发恰好落在 VSync 之前的一小段窗口内,这次标脏被这一帧 "接住",动画看起来是准的;如果落在 VSync 之后(哪怕只晚了 1ms),这一帧已经走完了脏变量处理阶段,新值只能等下一帧。同一份数据,一帧内落点不同,上屏时刻就差 16.7ms(120Hz 下 8.3ms)。
而组件自带的 .animate() 是怎么做的?它不把 "改属性值" 这件事交给你的回调,而是把插值本身挂在渲染帧链上:框架在每一帧的固定阶段拿到这一帧应处的进度,直接算属性值并进入布局绘制,中间没有 "写状态变量 → 等下一帧处理" 这一跳。少一跳,就少一次落点随机性。
这也解释了为什么现象是 "内容比容器快一帧" 而不是 "整体慢一帧":位移和透明度两个状态变量是在同一个 onFrame 回调里依次赋值的。它们必然进入同一批脏变量,一起被同一帧处理 ------ 理论上不该有相对偏移。但如果两者被不同的机制 驱动,比如容器位移走 Animator 写状态变量,而透明度走 .opacity(this.x) 加显式 animate,那它们就分别挂在两条链上:一条要等下一帧处理脏变量,另一条在渲染帧链内部直接推进,于是一帧的相对偏移就出来了。这也是为什么 "换一部分实现就对齐了"------ 你把其中一半搬回了渲染帧链。
错误写法与最小复现
// 错误示范:用一个 Animator 驱动两个状态变量
@Local sheetOffset: number = 100
@Local maskOpacity: number = 0
private animator: Animator | null = null
private buildAnimator(): Animator {
const a = Animator.create({
duration: 300,
easing: 'ease-in-out',
delay: 0,
fill: 'forwards',
direction: 'normal',
iterations: 1
})
a.onFrame((val: number) => {
// 两个状态变量在同一个回调里写,各占一次标脏名额
this.sheetOffset = 100 * (1 - val)
this.maskOpacity = val
})
a.onFinish(() => {
this.sheetOffset = 0
this.maskOpacity = 1
this.animator = null
})
return a
}
build() {
Stack() {
Column().width('100%').height('60%')
.backgroundColor(Color.White)
.translate({ y: this.sheetOffset + '%' })
// 遮罩单独挂 animate,和上面的状态变量不是一条链
}
.opacity(this.maskOpacity)
}
这段代码有四个问题叠在一起:
onFrame驱动的两个状态变量都要经过 "标脏 → 等 VSync → build",落点随机。- 遮罩层如果另行加了显式
animate,两条链的节拍不一致,相对偏移固定为一帧。 onFinish里又赋一次终值,这一帧可能和动画最后一帧叠加,产生一帧的 "跳变"。- 没有异常兜底:
Animator被页面销毁打断时,onFinish不一定触发,终值可能永远没写进去,下次打开时从半途状态开始。
正确做法:优先用渲染帧链,独立 Animator 只驱动 "非渲染" 的东西
方案 A(首选):动画全部交给组件 .animate()
V2 的组件属性动画挂在渲染帧链上,插值和绘制的时序是框架保证的,不存在 "标脏落点" 问题:
@ComponentV2
struct BottomSheet {
@Local expanded: boolean = false
build() {
Stack({ alignContent: Alignment.Bottom }) {
Column()
.width('100%')
.height('60%')
.backgroundColor(Color.White)
.translate({ y: this.expanded ? '0%' : '100%' })
.opacity(this.expanded ? 1 : 0)
.animate({
duration: 300,
curve: Curve.EaseInOut,
iterations: 1,
playMode: PlayMode.Normal,
onFinish: () => { /* 动画结束后的业务收尾,不要在这里再赋终值 */ }
})
// 遮罩同样走 animate,两者在同一个渲染帧链上推进
Column()
.width('100%').height('100%')
.backgroundColor('#66000000')
.opacity(this.expanded ? 1 : 0)
.animate({ duration: 300, curve: Curve.EaseInOut })
.onClick(() => { this.expanded = false })
}
}
}
要点:由布尔状态触发属性在两个终值之间的切换,动画交给 animate 插值。代码里不出现 "中间值",也就不存在 "谁比谁快一帧"。容器和遮罩被同一个布尔量驱动、挂在同一个时钟上,相对偏移从根本上消失了。
.animate() 还有两个需要知道的边界:
onFinish是动画链的回调,它和渲染帧同源,但不要在其中再赋一次终值------ 终值已由框架写入,重复赋值会产生一次额外的标脏,极端情况下触发一帧的多余重绘。- 属性动画隐含 "动画期间的写入优先":动画运行中如果有别处对同一属性赋值,可能造成动画被打断或值被覆盖。同一个属性不要有两个驱动源。
方案 B:必须用独立 Animator 时,只驱动 "不进渲染管线" 的数据
独立 Animator 的价值在它能驱动任意函数、任意对象,适合做不直接参与渲染的中间量:数值曲线采样、音效音量渐变、Canvas 内部描边宽度、手势跟手的位移积分。这些量即便晚一帧也不影响视觉一致性。
// 合法用法:Animator 驱动 Canvas 内部参数,Canvas 自己按帧重绘
a.onFrame((val: number) => {
this.canvasProgress = val // 普通变量,不作为渲染状态
this.canvasCtx.clearRect(0, 0, w, h)
this.canvasCtx.strokeStyle = '#0A59F7'
this.canvasCtx.lineWidth = 2
this.canvasCtx.beginPath()
this.canvasCtx.moveTo(x0, y0)
this.canvasCtx.lineTo(x0 + (x1 - x0) * val, y0) // 直接写进上下文
this.canvasCtx.stroke()
})
这里的 canvasProgress 不写进装饰器状态体系,Canvas 的绘制结果是 "当场生效" 的,不经过标脏排队,所以没有落点问题。
如果非要让独立 Animator 驱动组件属性,务实的做法是接受一帧级的偏差,并用 "锚点校正" 把它约束在一帧以内 :在 onFrame 里记录当前动画的期望进度,在组件 build 阶段(也就是渲染帧真正执行时)按期望进度计算显示值,让写入时刻和渲染时刻对齐:
private pendingProgress: number = 0 // Animator 回调写入
@Local renderProgress: number = 0 // 渲染帧读取
a.onFrame((val: number) => {
this.pendingProgress = val // 只记期望值,不触发渲染
})
// 用一个和渲染同源的轻量循环把期望值搬到渲染状态上
private tick = (): void => {
if (Math.abs(this.renderProgress - this.pendingProgress) > 1e-3) {
this.renderProgress = this.pendingProgress // 在这里标脏,下一帧渲染
}
if (this.animator) this.timerId = setTimeout(this.tick, 8)
}
这个方案的本质是:把 "任意时刻写入" 改成 "每帧固定时刻写入",用一帧的固定延迟换走落点的随机性。 固定的 1 帧偏差是可控的、叠加不会累积、所有被这样驱动的属性都整体后移同样一帧,视觉上一致;随机的落点才是肉眼能看出 "两个东西不同步" 的根因。
方案 C:多属性联动动画,只留一个驱动源
不管是 A 还是 B,多属性联动时只允许一个驱动源 :由一个布尔量、一个进度值、或一条 animate 链同时带起所有相关属性。不要出现 "位移走 Animator、透明度走 animate、圆角走另一条 animate" 的三驱动源结构 ------ 三条链各自的相位不同,错位是必然的,而且难以归因。
// 一个驱动源带三个属性
Column()
.translate({ y: this.expanded ? '0%' : '100%' })
.opacity(this.expanded ? 1 : 0)
.borderRadius(this.expanded ? 24 : 0)
.animate({ duration: 300, curve: Curve.EaseInOut }) // 一条链
还有几个会放大 "快一帧" 的坑
坑 1:在高刷设备上写死帧率假设。 60Hz 下 16.7ms 一帧、120Hz 下 8.3ms 一帧,如果你用 setInterval(fn, 16) 模拟帧驱动,在 120Hz 设备上就和真实 VSync 完全错相,抖动反而更明显。要跟渲染同源,就别自己造定时器。
坑 2:动画期间改了布局参数。 onFrame 里除了改 translate,还顺手改了 height、padding、margin 这类触发布局重算 的属性。布局重算本身要多花时间,在动画期间插入一次布局,会把这一帧的绘制流程推迟到下一帧,视觉上就是 "卡一下 + 跳一帧"。动画期间只碰 transform(translate / scale / rotate)和 opacity 这类不触发重排的属性。
坑 3:onFrame 里做了重活。 序列化、日志、正则、JSON.parse、找 DOM 等价物、给一组对象逐个赋值 ------ 回调本身的耗时会挤压这一帧的时间预算,一旦超过帧间隔,渲染掉帧,落点偏移从 "一帧级" 变成 "多帧级",动画看着就断断续续。
坑 4:onFinish 与动画末帧双写。 动画末帧已经把值推到终值,onFinish 再写一遍,产生一次冗余标脏;如果终值恰好和末帧不完全相等(比如末帧因浮点误差停在 0.9998),两次写入会让 UI 有一次肉眼可见的微跳。
坑 5:动画被页面销毁打断,状态停在半途。 独立 Animator 不随页面生命周期自动收尾。页面销毁或组件不可见时如果没停掉,回调可能继续向已销毁的组件写值;反过来,若在 onFinish 里才写入 "动画结束后的业务状态",被打断时这个状态永远不会落地,下次进入界面就从半途开始。需要在 aboutToDisappear 里显式 cancel 并按需写终值。
怎么验证 "到底是不是节拍问题"
用三个观测点判断,比凭感觉猜准:
- 时间戳对比 :在
onFrame里打Date.now(),同时在组件build的渲染逻辑里打一条时间戳。两者的时间差如果稳定在 0 或 1 帧,是节拍错位;如果时间差抖动、偶尔多帧,是掉帧或回调里干了重活。 - 两条动画链对照 :把其中一个属性搬到
.animate(),另一个留在Animator,观察相对偏移是否稳定存在。稳定存在 = 两条链,不是数值问题。 - 高刷 / 低刷交叉验证:同一份代码在 60Hz 和 120Hz 设备对比,偏移的绝对值变小但相对 "每帧一位" 的关系不变 = 节拍问题;偏移随设备随机跳 = 数值或性能问题。
排查清单
✅ 视觉动画优先用组件 .animate(),不引入独立 Animator 作为 UI 驱动源 ✅ 独立 Animator 只驱动非渲染中间量(Canvas 参数、音量、数据采样) ✅ 多属性联动动画只保留一个驱动源,避免 "位移走 Animator、透明度走 animate" 的双链结构 ✅ 需要独立驱动组件属性时,用 "每帧固定时刻写入",接受固定一帧延迟换确定性 ✅ onFrame 里只碰 translate / scale / rotate / opacity,不碰触发布局的属性 ✅ onFrame 内不做序列化、日志刷屏、批量赋值等重活 ✅ onFinish 不再重复赋终值,终值由动画链负责 ✅ 页面销毁时显式停掉独立 Animator,并补齐业务终态 ✅ 不用 setInterval(16) 模拟帧驱动,避免与高刷设备 VSync 错相 ✅ 用 "时间戳对比 + 双链对照 + 高刷交叉" 三点法确认是节拍问题还是数值问题
Animator 只保证按时间给你插值后的数值,不保证这些数值在正确的那一帧上被渲染。回调写入和 VSync 之间是一段没有约定的窗口,落在窗口前半段就被这一帧接住,落在后半段就晚一帧。视觉动画交给渲染帧链(.animate()),独立 Animator 留给不进渲染管线的中间量,多属性联动只留一个驱动源。下一次弹层内容和壳体差那么一帧的时候,先别去调曲线参数 ------ 数一数这份动画,到底有几条驱动链。
