更新记录

1.0.3（2026-05-29）

新增ios播放lottie动画完成的回调

1.0.2（2026-05-24）

修复web动画播放失败问题

1.0.1（2026-05-24）

添加动画播放完成回调

平台兼容性

uni-app(3.7.8)

uni-app x(3.7.8)

zl-lottie

基于 Lottie 的跨平台动画组件，支持 Android、iOS、HarmonyOS、Web 和微信小程序。

平台支持

安装

1. 导入插件

将 zl-lottie 文件夹放入项目的 uni_modules 目录。

2. 安装 Web 平台依赖

cd uni_modules/zl-lottie/utssdk/web
npm install

3. 安装微信小程序平台依赖

cd uni_modules/zl-lottie/utssdk/mp-weixin
npm install

注意：Android 和 iOS 平台的原生依赖通过 config.json 自动管理，无需手动安装。

4. 自定义调试基座（Android/iOS）

由于使用了第三方原生 SDK（lottie-android / lottie-ios），App 端需要自定义调试基座才能运行：

• HBuilderX → 运行 → 运行到手机或模拟器 → 运行基座选择 → 自定义调试基座
• 首次使用需通过云打包生成自定义基座

使用方式

Android / iOS（组件方式）

在模板中使用组件标签：

<template>
  <zl-lottie 
    ref="lottieRef"
    :filePath="filePath"
    :loop="true"
    @statechange="onStateChange"
    :style="{height: '300px'}"
  />
</template>

<script lang="uts">
export default {
  data() {
    return {
      filePath: 'https://assets9.lottiefiles.com/packages/lf20_PBgNop.json'
    }
  },
  methods: {
    playAnimation() {
      this.$refs["lottieRef"].playAnimation()
    },
    pauseAnimation() {
      this.$refs["lottieRef"].pauseAnimation()
    },
    resumeAnimation() {
      this.$refs["lottieRef"].resumeAnimation()
    },
    onStateChange(e : Map<string, any>) {
      console.log(JSON.stringify(e.get("detail")))
    }
  }
}
</script>

HarmonyOS（native-view 方式）

需要使用 HBuilderX 4.61+ 版本

<template>
  <native-view id="harmonyLottie" :style="{width:'100%',height:'300px'}" @init="onHarmonyInit"></native-view>
</template>

<script lang="uts">
import { ZlLottieHarmony } from '@/uni_modules/zl-lottie'

export default {
  data() {
    return {
      harmonyLottieController: null as ZlLottieHarmony | null
    }
  },
  methods: {
    onHarmonyInit(e : UniNativeViewInitEvent) {
      const element : UniNativeViewElement = e.detail.element
      this.harmonyLottieController = new ZlLottieHarmony(element)
    },
    playAnimation() {
      if (this.harmonyLottieController != null) {
        this.harmonyLottieController!.setFilePath('https://assets9.lottiefiles.com/packages/lf20_PBgNop.json')
        this.harmonyLottieController!.setLoop(true)
        this.harmonyLottieController!.playAnimation()
      }
    },
    pauseAnimation() {
      this.harmonyLottieController?.pauseAnimation()
    },
    resumeAnimation() {
      this.harmonyLottieController?.resumeAnimation()
    },
    cancelAnimation() {
      this.harmonyLottieController?.cancelAnimation()
    }
  }
}
</script>

Web（函数方式）

<template>
  <view id="lottieContainer" :style="{width:'100%',height:'300px'}"></view>
</template>

<script lang="uts">
import { loadAnimation } from '@/uni_modules/zl-lottie'
import type { ZlLottieAnimationController } from '@/uni_modules/zl-lottie'

export default {
  data() {
    return {
      animationController: null as ZlLottieAnimationController | null
    }
  },
  methods: {
    playAnimation() {
      const container = document.getElementById('lottieContainer')
      if (container != null) {
        this.animationController = loadAnimation({
          path: 'https://assets9.lottiefiles.com/packages/lf20_PBgNop.json',
          container: container,
          loop: true,
          autoplay: true,
          renderer: 'svg',
          animationData: null
        })
      }
    },
    pauseAnimation() {
      this.animationController?.pause()
    },
    resumeAnimation() {
      this.animationController?.play()
    }
  }
}
</script>

微信小程序（函数方式）

<template>
  <canvas id="lottieCanvas" type="2d" :style="{width:'100%',height:'300px'}"></canvas>
</template>

<script lang="uts">
import { setup, loadAnimation } from '@/uni_modules/zl-lottie'
import type { ZlLottieAnimationController } from '@/uni_modules/zl-lottie'

export default {
  data() {
    return {
      animationController: null as ZlLottieAnimationController | null
    }
  },
  methods: {
    playAnimation() {
      uni.createSelectorQuery().select('#lottieCanvas').node().exec((res : any) => {
        if (res != null && res.length > 0) {
          const canvas = res[0].node
          if (canvas != null) {
            setup(canvas)
            this.animationController = loadAnimation({
              path: 'https://assets9.lottiefiles.com/packages/lf20_PBgNop.json',
              animationData: null,
              canvas: canvas,
              loop: true,
              autoplay: true
            })
          }
        }
      })
    },
    pauseAnimation() {
      this.animationController?.pause()
    },
    resumeAnimation() {
      this.animationController?.play()
    }
  },
  // 页面退出时销毁动画
  onUnload() {
    if (this.animationController != null) {
      this.animationController!.destroy()
    }
  }
}
</script>

组件属性（Android / iOS）

组件方法（Android / iOS）

组件事件（Android / iOS）

HarmonyOS 控制器 API

ZlLottieHarmony 方法

函数 API（Web / 微信小程序）

Web 平台

微信小程序平台

ZlLottieAnimationController 方法

开发文档

• UTS 语法
• UTS API插件
• UTS uni-app兼容模式组件
• UTS 标准模式组件