动画曲线参数填对了,时序却总快一帧,Animator 的驱动节拍和 UI 标脏不在同一个时钟

一个底部弹层(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)
}

这段代码有四个问题叠在一起:

  1. onFrame 驱动的两个状态变量都要经过 "标脏 → 等 VSync → build",落点随机。
  2. 遮罩层如果另行加了显式 animate,两条链的节拍不一致,相对偏移固定为一帧。
  3. onFinish 里又赋一次终值,这一帧可能和动画最后一帧叠加,产生一帧的 "跳变"。
  4. 没有异常兜底: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 并按需写终值。

怎么验证 "到底是不是节拍问题"

用三个观测点判断,比凭感觉猜准:

  1. 时间戳对比 :在 onFrame 里打 Date.now(),同时在组件 build 的渲染逻辑里打一条时间戳。两者的时间差如果稳定在 0 或 1 帧,是节拍错位;如果时间差抖动、偶尔多帧,是掉帧或回调里干了重活。
  2. 两条动画链对照 :把其中一个属性搬到 .animate(),另一个留在 Animator,观察相对偏移是否稳定存在。稳定存在 = 两条链,不是数值问题。
  3. 高刷 / 低刷交叉验证:同一份代码在 60Hz 和 120Hz 设备对比,偏移的绝对值变小但相对 "每帧一位" 的关系不变 = 节拍问题;偏移随设备随机跳 = 数值或性能问题。

排查清单

✅ 视觉动画优先用组件 .animate(),不引入独立 Animator 作为 UI 驱动源 ✅ 独立 Animator 只驱动非渲染中间量(Canvas 参数、音量、数据采样) ✅ 多属性联动动画只保留一个驱动源,避免 "位移走 Animator、透明度走 animate" 的双链结构 ✅ 需要独立驱动组件属性时,用 "每帧固定时刻写入",接受固定一帧延迟换确定性 ✅ onFrame 里只碰 translate / scale / rotate / opacity,不碰触发布局的属性 ✅ onFrame 内不做序列化、日志刷屏、批量赋值等重活 ✅ onFinish 不再重复赋终值,终值由动画链负责 ✅ 页面销毁时显式停掉独立 Animator,并补齐业务终态 ✅ 不用 setInterval(16) 模拟帧驱动,避免与高刷设备 VSync 错相 ✅ 用 "时间戳对比 + 双链对照 + 高刷交叉" 三点法确认是节拍问题还是数值问题

Animator 只保证按时间给你插值后的数值,不保证这些数值在正确的那一帧上被渲染。回调写入和 VSync 之间是一段没有约定的窗口,落在窗口前半段就被这一帧接住,落在后半段就晚一帧。视觉动画交给渲染帧链(.animate()),独立 Animator 留给不进渲染管线的中间量,多属性联动只留一个驱动源。下一次弹层内容和壳体差那么一帧的时候,先别去调曲线参数 ------ 数一数这份动画,到底有几条驱动链。