权重化帧动画：打造流畅细腻的卡片动画体验

在 HarmonyOS 互动卡片（Live Form）开发中，帧动画是实现富有表现力视觉效果的核心手段。然而，互动卡片的运行环境与普通应用不同——卡片进程资源受限、生命周期短暂、且无法使用 XComponent 等重量级渲染方案。如何在如此苛刻的条件下实现流畅、细腻的逐帧动画？本文将以 LiveCard 项目中的睡眠卡片为例，深入讲解一种基于 权重化帧序列 的轻量级动画方案，并对比四种卡片的动画实现差异。

帧动画基础模型

FrameItem 数据结构

睡眠卡片同时管理两套动画序列：憨憨（hanhan）角色的 47 帧动画和三叶草（clover）气球的 52 帧动画。每帧由一个 FrameItem 对象描述：

// [entry/src/main/ets/livecardability/pages/SleepLiveCard.ets]
class FrameItem {
  public src: Resource;
  public weight: number;

  constructor(src: Resource, weight: number = 1) {
    this.src = src;
    this.weight = weight;
  }
}

FrameItem 只有两个字段：src 指向 rawfile 目录下的图片资源，weight 是该帧的权重值（默认 1）。这个看似简单的结构，却是整个动画节奏控制的核心。

权重机制的设计思路

传统帧动画通常采用等间隔切换——每帧停留相同时间。这种方式的局限性很明显：当动画需要"慢起-快跑-缓停"等节奏变化时，要么插入大量重复帧来延长停留时间（浪费内存），要么借助复杂的贝塞尔曲线插值（需要 Canvas 或属性动画支持）。

权重化方案另辟蹊径：不直接指定每帧的显示时长，而是通过权重值间接控制。权重越大，该帧在总动画时长中占据的时间比例就越大。这样，一组帧序列仅通过调整权重值，就能实现丰富多变的节奏效果。

// 憨憨动画片段的权重设计示例
private hanhanFrames: FrameItem[] = [
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame01-17.png'), 17), // 第一段：缓慢睁眼（占 17 份权重）
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame18.png')),        // 单帧过渡（默认 1 份权重）
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame19.png')),
  // ... 中间快速过渡帧 ...
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame28-38.png'), 11), // 停顿蓄力（11 份权重）
  // ... 动作帧 ...
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame47.png'), 2.5),   // 细腻动作（2.5 份权重）
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame48.png'), 2.5),
  // ... 更多 2.5 权重帧 ...
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame80-85.png'), 6),  // 收尾缓动（6 份权重）
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame86-88.png'), 3),
  new FrameItem($rawfile('sleep/animate/sleep_hanhan_frame89-95.png'), 7),
];

这里有两个值得注意的设计细节：

1. 权重值类型是 number 而非 int。像 2.5 这样的浮点权重值允许对帧时长进行亚整数级精调，这对于让关键帧过渡"刚刚好"非常有用。
2. 权重值的含义：理论上，权重为 17 的帧的停留时间是权重为 1 的帧的 17 倍。这避免了在图片资源层面复制 17 次同一张图片，仅在时间分配上实现"等效重复"。

时间轴计算算法

累积时间数组的构建

权重本身不是时间，需要将其映射到以毫秒为单位的实际时间轴上。buildCumulativeTime 函数完成了这个转换：

// [entry/src/main/ets/livecardability/pages/SleepLiveCard.ets]
private buildCumulativeTime(frames: FrameItem[]): number[] {
  const totalWeight = frames.reduce((sum: number, f: FrameItem) => sum + f.weight, 0);
  let cumulative = [0];
  for (let i = 0; i < frames.length; i++) {
    cumulative.push(cumulative[i] + frames[i].weight / totalWeight * LIVE_CARD_DURATION);
  }
  return cumulative;
}

算法流程如下：

1. 计算所有帧的权重总和 totalWeight
2. 遍历每帧，计算 (当前帧权重 / 总权重) × 总动画时长，得到该帧的绝对时间片（毫秒）
3. 累加这些时间片，得到一个单调递增的累积时间数组

例如，假设只有 3 帧，权重分别为 [2, 1, 1]，总时长 3500ms，则累积时间数组为 [0, 1750, 2625, 3500]。这意味着第 0 帧占据 [0, 1750) 区间，第 1 帧占据 [1750, 2625)，第 2 帧占据 [2625, 3500]。

getFrameByElapsed：实时帧定位

// [entry/src/main/ets/livecardability/pages/SleepLiveCard.ets]
private getFrameByElapsed(elapsed: number, cumulativeTime: number[], totalFrames: number): number {
  for (let i = 1; i < cumulativeTime.length; i++) {
    if (elapsed < cumulativeTime[i]) {
      return i - 1;
    }
  }
  return totalFrames - 1;
}

该函数接收经过时间 elapsed，在累积时间数组中进行线性查找，找到第一个大于 elapsed 的累积时间值，返回其前一个索引。如果 elapsed 超过了所有累积时间值（通常在动画结束时），则返回最后一帧。

这是一个典型的 分段查找 算法，时间复杂度 O(n)。对于 47 或 52 帧的序列，线性查找完全够用。如果帧数达到数百甚至上千，可以考虑二分查找优化，但在互动卡片场景中不必过度设计。

双序列同步播放

睡眠卡片的一个独特之处在于，它同时管理了两套帧序列——憨憨和三叶草。两套序列使用同一个 animStartTime 和同一个 setInterval 定时器，但各自维护独立的 cumulativeTime 数组和 currentFrameIndex 状态：

private startImageSync(): void {
  this.stopCoverSync();
  this.animStartTime = Date.now();
  this.imageSyncTimer = setInterval(() => {
    const elapsed = Date.now() - this.animStartTime;
    if (elapsed >= LIVE_CARD_DURATION) {
      this.currentHanhanFrameIndex = this.hanhanFrames.length - 1;
      this.currentCloverFrameIndex = this.cloverFrames.length - 1;
      clearInterval(this.imageSyncTimer);
      return;
    }
    const newHanhanFrame = this.getFrameByElapsed(elapsed, this.hanhanCumulativeTime, this.hanhanFrames.length);
    const newCloverFrame = this.getFrameByElapsed(elapsed, this.cloverCumulativeTime, this.cloverFrames.length);
    // ...
  }, 16);
}

这种设计保证了两个角色的动画在时间轴上严格对齐——无论各自的帧数和权重分布如何，它们总是在相同的实际时间完成整个动画周期。

setInterval 定时驱动

16ms 刷新率的选择

互动卡片无法使用 requestAnimationFrame（卡片进程没有动画帧调度能力），因此选择 setInterval 作为驱动源。睡眠卡片将间隔设为 16ms，对应约 60fps 的刷新率：

this.imageSyncTimer = setInterval(() => {
  // 动画逻辑...
}, 16);

这里有一个微妙的权衡：16ms 间隔并不意味着实际帧率一定能达到 60fps。setInterval 的精度受事件循环负载影响，实际回调间隔可能有 1-5ms 的抖动。但关键在于，我们的动画并非依赖定时器来精确控制每一帧的显示时机——定时器只负责"检查当前时间并计算应显示的帧"，实际的帧切换逻辑由 getFrameByElapsed 基于绝对时间差来计算。

单向驱动与防回跳

睡眠卡片的帧索引更新采用了 单向递增 策略：

if (newHanhanFrame > this.currentHanhanFrameIndex) {
  this.currentHanhanFrameIndex = newHanhanFrame;
}

只允许帧索引向前推进，绝不回退。这一设计有两个好处：

1. 避免视觉抖动：即使某次回调因系统负载延迟触发，导致计算得到的帧号小于当前已显示的帧号，也不会将画面回退到之前的帧。
2. 兼容跳帧：当定时器回调被延迟时，elapsed 值可能跨越多个帧的时间区间，getFrameByElapsed 会直接跳到正确的当前帧，实现自动跳帧。

动画终止条件

当 elapsed >= LIVE_CARD_DURATION（3500ms）时，动画将两套序列同时定位到最后一帧并清除定时器：

if (elapsed >= LIVE_CARD_DURATION) {
  this.currentHanhanFrameIndex = this.hanhanFrames.length - 1;
  this.currentCloverFrameIndex = this.cloverFrames.length - 1;
  clearInterval(this.imageSyncTimer);
  return;
}

注意这里没有通过 stopCoverSync 来停止，而是直接 clearInterval，是因为在定时器回调内部执行 clearInterval 是安全的——当前回调执行完毕后，该定时器不会再次触发。

动画节奏控制

权重值的节奏映射

权重化帧动画最强大的能力在于，通过调整一个数值就能控制整段动画的节奏。让我们分析憨憨动画序列的节奏设计：

帧区间	权重值	效果	视觉描述
frame01-17	17	极慢（占 ~36% 时长）	憨憨从睡眠中缓缓睁眼，营造慵懒氛围
frame18-27	1×10	正常过渡	眼睛完全睁开，表情逐步清醒
frame28-38	11	较慢（占 ~23% 时长）	停顿观察，似乎意识到已经天亮
frame39-46	1×8	快速过渡	快速完成起床动作序列
frame47-58	2.5×12	细腻中速（占 ~32% 时长）	伸展四肢，每个动作都清晰可见
frame59-65	1×7	正常过渡	继续完成起床收尾
frame68-79	3×4	较慢（占 ~12% 时长）	最后调整姿态，趋于稳定
frame80-85	6	慢速（占 ~13% 时长）	完全清醒，进入稳定站立状态
frame86-95	3+7	逐渐放缓	动画收尾，自然过渡到最终画面

整个动画呈现出 慢→快→慢→快→慢 的波浪式节奏，完美模拟了从睡眠到清醒的自然过程。

"慢-快-慢"的实现原理

传统属性动画通过贝塞尔曲线（如 cubic-bezier(0.42, 0, 0.58, 1)）实现缓动效果。权重化帧动画则以离散帧的方式近似连续缓动曲线。

假设我们要实现"慢-快-慢"效果——帧序列共 10 帧，总时长 3500ms：

权重分布: [3, 2, 1, 1, 1, 1, 1, 1, 2, 3]
时间分配: 第0帧占 525ms, 第1帧占 350ms, 第2-7帧各占 175ms, 第8帧 350ms, 第9帧 525ms

起始和结束帧的权重高（停留时间长），中间帧的权重低（快速掠过）。这与 ease-in-out 曲线的形态完全一致——在动画曲线的两端，函数的斜率变小（变化慢），中间斜率变大（变化快）。

帧合并优化与权重协同

观察憨憨动画中的 frame01-17.png，文件名暗示这张图片实际包含 17 帧的合并内容。这是一种 视觉压缩 策略：当多帧在动画中连续且变化很小时，可以直接将这些帧合并为一张静态图，并通过高权重值来等效延长显示时间。这样既减少了图片资源加载量，又保持了视觉上的"停留感"。

三叶草动画也使用了同样的策略：sleep_balloon_frame23-27.png（权重 5）、sleep_balloon_frame28-30.png（权重 3）等。

性能优化要点

图片资源大小控制

互动卡片运行在卡片托管进程中，系统对卡片的内存占用有严格限制。图片资源是内存消耗的大头，因此需要严格控制每帧图片的大小：

• rawfile 目录下的动画帧图片建议使用 PNG 或 WebP 格式，尺寸不宜超过卡片实际渲染分辨率
• 对于变化微小的连续帧，可以合并为一张图片（如上文提到的 frame01-17.png），减少文件数量和加载开销
• 优先使用 ImageFit.Contain 而非 Cover，避免大图缩放导致额外性能开销

3500ms 上限的硬约束

LIVE_CARD_DURATION = 3500 定义在全局常量中：

// [entry/src/main/ets/model/common/FormCardConstant.ets]
export const LIVE_CARD_DURATION: number = 3500;

3.5 秒的上限设计基于两点考虑：一是互动卡片的默认展示时长通常不超过 5 秒，过长的动画可能在用户浏览完卡片内容前尚未结束；二是避免长时间占用定时器和图片资源，减少对卡片其他交互响应的影响。

避免丢帧的策略

帧动画最常见的质量问题是"卡顿"或"丢帧"。本项目通过以下方式缓解：

1. 基于绝对时间的帧计算：getFrameByElapsed 不依赖定时器的稳定触发，即使某次回调延迟了 50ms，也只是跳过了中间帧，不会造成画面停滞。
2. 跳帧优先于追赶：动画永远不会尝试"补播"中间帧。如果系统负载导致某次回调被延迟，直接跳到正确的当前帧。在 60fps 下，偶尔跳 1-2 帧用户几乎无法感知，但画面"卡住"就会很明显。
3. 定时器生命周期管理：在 aboutToDisappear 中调用 stopCoverSync 清理定时器，避免卡片销毁后仍有定时器在后台运行。

双向递增检查的微优化

在 startImageSync 中，对两个帧序列分别执行了 > 检查后才赋值 State 变量：

if (newHanhanFrame > this.currentHanhanFrameIndex) {
  this.currentHanhanFrameIndex = newHanhanFrame;
}
if (newCloverFrame > this.currentCloverFrameIndex) {
  this.currentCloverFrameIndex = newCloverFrame;
}

这是一个重要的性能考量——State 变量的每一次赋值都可能触发 ArkUI 的重新渲染。通过条件判断过滤掉"不变"的赋值，可以避免不必要的组件刷新。

跨卡片对比

LiveCard 项目包含四种互动卡片，它们都涉及不同程度的动画效果，但实现方案各有特色：

卡片	动画类型	动画方案	驱动方式	核心特点
睡眠卡片	权重化逐帧动画	FrameItem + getFrameByElapsed	setInterval 16ms	双序列同步、权重节奏、单向递增
运动卡片	等间隔帧动画 + 属性动画	ImageFrameInfo 数组	setInterval 等间隔 + keyframeAnimateTo	状态驱动、GIF 叠加、卡路里计数
音乐卡片	Canvas 帧动画 + 帧序列	Canvas drawImage + 逐帧递增	setInterval 等间隔	专辑封面 3D 变换、Canvas 合成
快递卡片	无帧动画（陀螺仪驱动）	animateTo + 陀螺仪数据	Gyroscope 传感器回调	物理交互、实时缩放位移

睡眠卡片 vs 运动卡片

运动卡片 [entry/src/main/ets/livecardability/pages/ExerciseLiveCard.ets] 的帧序列 CELEBRATE_IMAGES 和 STRETCHING_IMAGES 采用 ImageFrameInfo[] 结构（仅包含 src 字段，无权重），使用等间隔切换：

let duration = 3000 / totalFrames;
this.imageSyncTimer = setInterval(() => {
  if (this.currentImagesIndex === totalFrames - 1) {
    this.stopImageSync();
  } else {
    this.currentImagesIndex = (this.currentImagesIndex + 1) % totalFrames;
  }
}, duration);

每帧停留时间相等，节奏均匀。这是因为运动卡片的动画主要用于展示标准运动姿态，不需要"慢-快-慢"的情感化节奏。

此外，运动卡片在完成状态还叠加了 keyframeAnimateTo 实现的缩放动画和 GIF 动图，形成了"帧序列 + 属性动画 + GIF"三层混合动画，实现更丰富的视觉层级。

睡眠卡片 vs 音乐卡片

音乐卡片 [entry/src/main/ets/livecardability/pages/MusicLiveCard.ets] 在切歌时使用 SWITCH_FRAME_IMAGES（25 帧），在播放时使用 DANCE_FRAME_IMAGES（26 帧）。其核心差异在于：

• 渲染方式：音乐卡片采用 Canvas 绘制，将专辑封面和帧序列通过 drawImage 合成，并叠加 3D 旋转（rotateX/Y/Z）和缩放变换，实现更复杂的视觉特效。
• 帧进度计算：音乐卡片采用简单的逐帧递进（this.currentCoverFrame++），而非基于时间索引查找。这是因为音乐卡片的动画固定为 25 帧，每帧等间隔，不需要权重化节奏控制。
• 专辑封面旋转：播放状态下，专辑封面以每 50ms 旋转 3 度的匀速旋转，通过独立的 rotateTimer 驱动。

睡眠卡片 vs 快递卡片

快递卡片 [entry/src/main/ets/livecardability/pages/DeliveryLiveCard.ets] 完全不使用帧动画，其"憨憨小人"的左右摆动完全由陀螺仪传感器驱动。核心差异在于：

• 驱动源：传感器数据（Gyroscope）vs 定时器
• 动画方式：animateTo 属性动画 vs 帧序列切换
• 交互模型：用户通过倾斜设备实时控制 vs 全自动线性播放

总结

权重化帧动画是 HarmonyOS 互动卡片场景下一套轻量而强大的动画方案。其核心思想可以概括为：用一个标量权重值将动画的"内容"（帧图片）和"节奏"（时间分配）解耦。开发者只需调整权重数组，就能像编排舞蹈一样控制动画的快慢节奏，而无需修改图片资源或重绘精灵表。

这种方案特别适用于以下场景：

• 动画帧数较多（30-60 帧），需要精细控制每帧停留时间
• 需要"慢-快-慢"等情感化节奏的叙事型动画
• 需要在资源受限的卡片进程中实现流畅的逐帧效果
• 需要多套帧序列在相同时间轴上同步播放

对于设计更简单的动画（如等间隔切换、属性动画、传感器驱动），可以选择运动卡片或音乐卡片的方案。理解不同方案的适用场景，才能在互动卡片开发中做出最优的技术选型。