更新记录

1.1.2（2026-02-25）

发布第一版

平台兼容性

uni-app(3.8.0)

<lui-animator />

全平台 Lottie 动画组件，支持文本/图片替换与元素点击。

Lottie 由 Airbnb 开源，可在应用中带来流畅的矢量动画。本组件在 微信小程序 使用 lottie-miniprogram + Canvas 2D 渲染，在 App / H5 使用 lottie-web + SVG 渲染。

渲染与替换策略

• 文本替换（全平台）：通过 textMap prop 或 replaceText() / replaceTexts() 在加载前修改 JSON，仅改文字、保留原字体/颜色；或通过 updateDocumentData() 在 domLoaded 后运行时更新。
• 图片替换（全平台）：通过 imageMap prop 或 replaceImage() / replaceImages()，按 asset id/名称匹配；H5/App 内嵌 base64，小程序使用本地临时路径。
• 元素点击（仅 H5/App）：通过 clickableIds 指定可点击的 asset/图层 id，点击时触发 elementClick 事件。

快速开始

0. 安装依赖

App / H5：

npm install lottie-web
# 或
yarn add lottie-web

微信小程序：

npm install lottie-miniprogram
# 或
yarn add lottie-miniprogram

1. 引入组件并指定动画数据

<lui-animator :frames="lottieJsonData" />

2. 声明式文本/图片替换

<!-- 按图层名或文本内容替换文字，保留原样式 -->
<lui-animator
  :frames="data"
  :textMap="{ '24.4元': '99.9元', '用户昵称': '张三' }"
/>

<!-- 按 asset id 替换图片 -->
<lui-animator
  :frames="data"
  :imageMap="{ 'image_0': 'https://example.com/avatar.jpg' }"
/>

3. 元素点击（仅 H5/App）

<lui-animator
  :frames="data"
  :clickable-ids="['image_3']"
  @elementClick="onElementClick"
/>

onElementClick({ id, event }) {
  console.log('点击了元素:', id);
}

参数 (Props)

事件 (Events)

方法 (Methods)

通过 ref 调用，例如：this.$refs.lottie.play()。

动画控制（兼容 lottie-web 标准）

• play() — 播放
• stop() — 停止
• pause() — 暂停
• setSpeed(speed) — 设置播放速度
• gotoAndStop(value, isFrame) — 跳转到某一帧/时间并停止
• gotoAndPlay(value, isFrame) — 跳转到某一帧/时间并播放
• setDirection(direction) — 设置播放方向
• playSegments(segments, forceFlag) — 播放指定片段
• setLocationHref(href) — 设置 base URL（如 SVG 内链接）
• setSubframe(flag) — 是否使用子帧

文本替换（源数据级，全平台）

• replaceText(matcher, text) — 单处替换：matcher 为图层名/文本内容字符串，或 { layerName?, content?, layerIndex? }
• replaceTexts(map) — 批量替换：{ '原文本或图层名': '新文本' }
• clearTextReplacements() — 清除所有命令式文本替换并重新初始化

图片替换（源数据级，全平台）

• replaceImage(assetId, imageUrl) — 按 asset id/名称替换一张图片
• replaceImages(map) — 批量替换：{ 'asset id': '图片 URL' }
• clearImageReplacements() — 清除所有命令式图片替换并重新初始化

运行时文本更新（domLoaded 后）

• updateDocumentData({ layerName?, layerIndex?, data }) — 直接更新文本图层内容，无需重载动画；data 支持 { t?, s?, fc?, f?, j?, lh?, ls? }，返回 boolean 表示是否成功

其它

• getAnimInstance() — 返回底层 lottie 实例（便于高级用法）
• inspectTextLayers() — 列出当前动画所有文本图层信息（调试用）

使用示例

命令式替换文本

this.$refs.lottie.replaceText('24.4元', '99.9元');
this.$refs.lottie.replaceText({ layerName: '标题' }, '新标题');
this.$refs.lottie.replaceTexts({ '24.4元': '99.9元', '用户昵称': '张三' });

命令式替换图片

this.$refs.lottie.replaceImage('image_0', 'https://example.com/avatar.jpg');
this.$refs.lottie.replaceImages({ 'image_0': avatarUrl, 'image_1': goodsUrl });

运行时更新文本（domLoaded 后）

this.$refs.lottie.updateDocumentData({
  layerName: '分数',
  data: { t: '100' }
});

平台说明

• 微信小程序：需安装 lottie-miniprogram，使用 Canvas 2D；图片替换在 load 前写入 JSON，clickableIds / elementClick 不生效。
• App / H5：需安装 lottie-web，使用 SVG 渲染；支持 clickableIds 与 elementClick，图片可为网络 URL（组件内转 base64）。