更新记录

1.1.9（2026-05-31）

优化组件

1.1.8（2026-05-31）

1

1.1.7（2026-05-31）

文件乱码

平台兼容性

uni-app(4.73)

uni-app x(4.72)

animation-Lottie Lottie 动画组件

一款 Lottie 动画组件，提供丰富的 API 接口，支持声明式/命令式文本与图片替换，兼容 WEB、微信小程序、安卓、iOS、鸿蒙。

文档链接

📚 组件详细文档请访问以下站点（基于 lime-lottie 原版文档，API 基本一致）：

• Lottie 组件文档 - 站点 1
• Lottie 组件文档 - 站点 2
• Lottie 组件文档 - 站点 3

安装方法

1. 在 uni-app 插件市场中搜索并导入 animation-Lottie
2. 导入后可能需要重新编译项目
3. 在 pages.json 中配置 easycom（见下方「组件选用提示」），页面中直接使用 animation-Lottie
4. 微信小程序和 Web 需要安装依赖：

微信小程序

npm install lottie-miniprogram --save

WEB

npm install lottie-web --save

组件选用提示

推荐：业务页面直接使用 animation-Lottie，配合 easycom 无需手动 import。参考示例工程 pages/index/index.vue。

在 pages.json 中配置 easycom（示例工程已内置）：

{
  "easycom": {
    "autoscan": true,
    "custom": {
      "^animation-[Ll]ottie$": "@/uni_modules/animation-Lottie/components/animation-Lottie/animation-Lottie.vue"
    }
  }
}

页面中直接使用，无需 import：

<template>
  <animation-Lottie
    ref="lottieRef"
    src="/static/animation.json"
    :loop="false"
    :autoplay="true"
    l-style="width:100%"
    @ready="onLottieReady"
    @complete="onLottieComplete"
  />
</template>

<script>
export default {
  components: {},
  methods: {
    onLottieReady() {},
    onLottieComplete() {},
  },
}
</script>

若必须使用底层 Z-lottie，需在页面中手动引用：

<template>
  <Z-lottie src="/static/animation.json" l-style="width:100%" />
</template>

<script>
import ZLottie from '@/uni_modules/animation-Lottie/components/Z-lottie/Z-lottie.vue'

export default {
  components: { ZLottie },
}
</script>

代码演示

基础用法

最简单的 Lottie 动画组件用法，只需要设置动画路径即可。

<animation-Lottie :l-style="{ height: '200px' }" src="https://example.com/animation.json"></animation-Lottie>

通过 ref 调用组件方法

通过 ref 可以直接调用组件暴露的方法来控制动画。

<view style="height:200px">
  <animation-Lottie ref="lottieRef" src="https://example.com/animation.json"></animation-Lottie>
</view>
<button @click="play">播放</button>
<button @click="pause">暂停</button>
<button @click="destroy">销毁</button>

import type { LimeLottie } from '@/uni_modules/animation-Lottie'

const lottieRef = ref<ZLottieComponentPublicInstance | null>(null)

const play = () => {
  lottieRef.value?.play()
}

const pause = () => {
  lottieRef.value?.pause()
}

const destroy = () => {
  lottieRef.value?.destroy()
}

动态加载动画

使用 loadAnimation 方法动态加载动画并获取 LimeLottie 实例。

<view style="height:200px">
  <Z-lottie ref="lottieRef"></Z-lottie>
</view>
<button @click="loadAndPlay">加载并播放</button>

import type { LimeLottie } from '@/uni_modules/animation-Lottie'

const lottieRef = ref<ZLottieComponentPublicInstance | null>(null)

const loadAndPlay = async () => {
  if (lottieRef.value == null) return

  const lottie = await lottieRef.value.loadAnimation('https://example.com/animation.json')
  lottie.setSpeed(2)
  lottie.play()
}

通过 loaded 事件动态加载

通过 loaded 事件获取 loadAnimation 函数，实现动态加载。

<view style="height:200px">
  <Z-lottie @loaded="onLoaded"></Z-lottie>
</view>
<button @click="loadAnimation1">加载动画 1</button>
<button @click="loadAnimation2">加载动画 2</button>

import type { LimeLottie } from '@/uni_modules/animation-Lottie'

// Object 在 uniappx 是 UTSJSONObject
type LoadAnimationFn = (url: string | UTSJSONObject) => Promise<LimeLottie>

const loadAnimationFn = ref<LoadAnimationFn | null>(null)

const onLoaded = (loadAnimation: LoadAnimationFn) => {
  loadAnimationFn.value = loadAnimation
}

const loadAnimation1 = async () => {
  if (!loadAnimationFn.value) return
  const lottie = await loadAnimationFn.value('https://example.com/animation1.json')
  lottie.play()
}

const loadAnimation2 = async () => {
  if (!loadAnimationFn.value) return
  const lottie = await loadAnimationFn.value('https://example.com/animation2.json')
  lottie.play()
}

自定义动画属性

设置动画的循环、自动播放和速度。

<Z-lottie
  src="https://example.com/animation.json"
  :loop="true"
  :autoplay="true"
  :speed="1.5"
></Z-lottie>

声明式文本/图片替换

通过 textMap、imageMap 在加载前替换动画内的文本与图片资源。

<Z-lottie
  src="/static/animation.json"
  :text-map="{
    '用户名': '张三',
    '欢迎语': { text: 'Hello World' }
  }"
  :image-map="{
    avatar: '/static/avatar.png',
    'img_0.png': 'https://example.com/badge.png'
  }"
  :image-replace-size="64"
></Z-lottie>

textMap 匹配规则： 图层名 (nm) 或原文本内容 → 新文本（字符串或 { text: string }）

imageMap 匹配规则： asset id 或 asset 名称 (nm) → 图片 URL 或 base64 Data URL

命令式文本/图片替换

运行时通过 ref 调用替换方法，适用于动态更新内容。

<Z-lottie ref="lottieRef" src="/static/animation.json"></Z-lottie>
<button @click="updateContent">更新内容</button>

const lottieRef = ref<ZLottieComponentPublicInstance | null>(null)

const updateContent = () => {
  // 替换单个文本（matcher 可为图层名、原文本，或 { layerName / content / layerIndex }）
  lottieRef.value?.replaceText('用户名', '李四')
  lottieRef.value?.replaceTexts({ 欢迎语: '晚上好' })

  // 替换图片
  lottieRef.value?.replaceImage('avatar', '/static/new-avatar.png')
  lottieRef.value?.replaceImages({ badge: 'https://example.com/new-badge.png' })
}

// 清除替换，恢复动画原始内容
const reset = () => {
  lottieRef.value?.clearTextReplacements()
  lottieRef.value?.clearImageReplacements()
}

快速预览

导入插件后，推荐直接使用封装组件查看演示效果：

<!-- 演示页位于 uni_modules/animation-Lottie/components/animation-Lottie -->
<animation-Lottie />

插件标签说明

Vue2 使用说明

本组件使用 Composition API（setup + defineComponent）。Vue2 项目必须先安装并注册 @vue/composition-api，否则运行时会报错：

TypeError: defineComponent is not a function

1. 安装依赖

npm install @vue/composition-api --save

微信小程序 / H5 还需安装对应 Lottie 依赖（见上方「安装方法」）。

2. 在 main.js 中注册

请按照 uni-app 官方教程 配置：

import Vue from 'vue'
import VueCompositionAPI from '@vue/composition-api'

Vue.use(VueCompositionAPI)

3. 重新编译

修改 main.js 或更新插件后，请停止并重新运行项目（HBuilderX：重新运行到模拟器/浏览器）。

API 文档

Props 属性说明

Events 事件

组件方法（通过 ref 调用）

通过 ref 可以调用组件实例的以下方法：

文本/图片替换相关方法在 App 端 为占位实现，调用无效果。

LimeLottie 实例方法

通过 loadAnimation 方法或 ready 事件可以获取 LimeLottie 实例，实例提供以下方法：

AnimationEventName 可选值：

• enterFrame - 每帧触发（未实现）
• loopComplete - 循环完成时触发
• complete - 动画完成时触发
• segmentStart - 片段开始时触发
• destroy - 销毁时触发

AnimationDirection 可选值：

• 1 - 正向播放
• -1 - 反向播放

支持与赞赏