更新记录

1.0.0（2026-01-31）

• 初始版本：
  • App-Android / App-iOS / App-HarmonyOS 原生 Lottie 视图
  • 本地 src 加载 JSON，支持 src 同级 images/ 图片资源目录
  • HarmonyOS 额外支持 src 传入 http(s) URL
  • 增加 debug prop（默认 false），用于控制组件/原生层日志开关
  • error 事件参数规范为 { code, message }，避免平台差异
  • 优化更新策略：speed/progress/autoPlay/loop 变更走方法调用，减少全量 setConfig 导致的重复加载
  • ref 类型命名为 HansLottieInstance

平台兼容性

uni-app x(4.87)

hans-lottie

uni-app x 原生 Lottie 组件，支持 App-Android / App-iOS / App-HarmonyOS。

仅支持 uni-app x 的 App 端，不支持 Web/小程序/传统 uni-app。

安装

• 将 uni_modules/hans-lottie 安装/拷贝到项目中
• 在 uni-app x 页面/组件中可直接使用 <hans-lottie />（默认 easycom 下无需手动注册）
• 如需显式引入（推荐用于类型提示/避免自动引入差异）：

import HansLottie from '@/uni_modules/hans-lottie/components/hans-lottie/hans-lottie.uvue'

资源准备

支持使用本地资源路径加载 Lottie JSON；如果动画引用了图片资源，默认从 src 同级目录的 images/ 读取。

目录结构示例：

static/lottie/demo/data.json
static/lottie/demo/images/*

基础用法

<template>
    <hans-lottie
        style="width:240px;height:240px"
        src="/static/lottie/demo/data.json"
        :autoPlay="true"
        :loop="true"
        :speed="1"
        :debug="false"
        @ready="onReady"
        @error="onError"
    />
</template>

<script setup lang="uts">
type HansLottieError = {
    code: string
    message: string
}

function onReady() {
    console.log("[hans-lottie]", "ready")
}
function onError(err: HansLottieError) {
    console.error("[hans-lottie]", "error", err)
}
</script>

通过 ref 控制播放

组件暴露了播放控制方法，可通过 ref 调用：

注意：ref 类型声明请使用 type（不要用 interface），否则在部分平台会触发运行时类型转换错误。

<template>
    <hans-lottie
        ref="lottieRef"
        style="width:240px;height:240px"
        src="/static/lottie/demo/data.json"
        :autoPlay="false"
        :loop="true"
    />
    <button @click="play">play</button>
    <button @click="pause">pause</button>
    <button @click="stop">stop</button>
</template>

<script setup lang="uts">
import { HansLottieInstance } from '@/uni_modules/hans-lottie'

const lottieRef = ref(null as HansLottieInstance | null)

function play() {
    const p = lottieRef.value
    if (p != null) p.play()
}
function pause() {
    const p = lottieRef.value
    if (p != null) p.pause()
}
function stop() {
    const p = lottieRef.value
    if (p != null) p.stop()
}
</script>

API

Props

• src: string：Lottie JSON 路径（建议以 /static/ 开头）
  • 图片资源动画：默认读取 src 同级目录的 images/（例如 /static/lottie/demo/images/*）
  • Android/iOS：仅支持本地资源路径（不支持网络 URL）
  • HarmonyOS：支持 http(s)://... 网络 URL
• autoPlay: boolean：是否自动播放，默认 true（当 progress 为 null 时生效）
• loop: boolean：是否循环，默认 true
• speed: number：播放速度，默认 1（范围 0..10，超出会被限制）
• progress: number | null：进度控制，默认 null
  • 取值范围 0..1
  • 设置为非 null 时会 seek(progress) 并 pause()（此时 autoPlay 不再生效，建议用 ref 控制播放）
• debug: boolean：是否开启日志，默认 false

Methods（通过 ref）

• play()
• pause()
• stop()
• seek(progress: number)：progress 会被限制到 0..1
• setSpeed(speed: number)：speed 会被限制到 0..10
• setLoop(loop: boolean)

Events

• ready：原生视图初始化完成且已应用配置
• error：初始化或更新配置时发生异常（回调参数为 { code, message }）

HarmonyOS 兼容性说明

HarmonyOS 端不同导出版本/特性组合的兼容性可能存在差异。若动画区域空白或日志出现 onDataFailed / data_failed：

1. 优先确认 src 可访问（本地路径是否正确、网络 URL 是否可访问）
2. 尝试用 bodymovin 5.x 重新导出，或简化动画（移除复杂蒙版/跟踪遮罩/表达式等）后再验证