播放控制与事件监听——API 一览

Player 对象基础

lottie.loadAnimation() 返回一个 player 对象，是你控制动画的句柄：

const anim = lottie.loadAnimation({ /* ... */ });

// anim 是 player 对象
console.log(anim.loopCount);    // 循环次数
console.log(anim.currentFrame); // 当前帧
console.log(anim.totalFrames);  // 总帧数

播放控制方法

方法	含义
`play()`	从头或从暂停位置开始播放
`stop()`	停止并回到第 0 帧
`pause()`	暂停在当前帧
`goToAndStop(frame, isFrame)`	跳到指定帧并停止。`isFrame=true` 表示 frame 参数是帧号，`false` 表示时间（秒）
`goToAndPlay(frame, isFrame)`	跳到指定帧并开始播放
`setDirection(dir)`	`1` = 正向播放，`-1` = 反向
`setSpeed(speed)`	倍速，1 = 正常，0.5 = 半速，2 = 两倍快
`playSegments(segments, forceFlag)`	播放指定帧范围。`segments` 是 `[[start, end]]` 数组
`destroy()`	销毁动画，释放内存（组件卸载时必须调用）

实战示例

// 跳到第 30 帧，停止
anim.goToAndStop(30, true);

// 跳到 1.5 秒处，继续播放
anim.goToAndPlay(1.5, false);

// 只播放第 20~50 帧
anim.playSegments([[20, 50]], true);

// 反向播放
anim.setDirection(-1);
anim.play();

// 0.5 倍速慢放
anim.setSpeed(0.5);

事件监听

player 对象提供了 addEventListener 方法：

事件	触发时机
`complete`	整个动画（或最后一段）播放完成
`loopComplete`	每次循环播放完成时（loopCount++）
`enterFrame`	每一帧都会触发（性能敏感，谨慎使用）
`frameChange`	帧变化时（比 enterFrame 略粗）
`config_ready`	JSON 配置加载完、开始渲染前
`data_failed`	JSON 文件加载失败（URL 错误、网络问题）
`loaded_images`	所有图片资源加载完
`DOMLoaded`	DOM 元素创建完成

示例

anim.addEventListener('complete', () => {
  console.log('动画播放完了');
});

anim.addEventListener('loopComplete', () => {
  console.log(`第 ${anim.loopCount} 次循环结束`);
  if (anim.loopCount >= 3) {
    anim.pause(); // 播 3 次后停止
  }
});

anim.addEventListener('enterFrame', () => {
  // 每一帧都调——注意性能
  console.log(`当前帧: ${anim.currentFrame}/${anim.totalFrames}`);
});

anim.addEventListener('data_failed', () => {
  console.error('动效文件加载失败');
});

与 React 的配合

在 React 组件里，事件监听的注册和清理也要放在 effect 里：

useEffect(() => {
  const anim = lottie.loadAnimation({ /* ... */ });

  const handleComplete = () => { /* ... */ };
  anim.addEventListener('complete', handleComplete);

  return () => {
    anim.removeEventListener('complete', handleComplete);
    anim.destroy();
  };
}, []);