Lottie 动画 - Semi Design Next

使用场景

Lottie 组件能够便捷简单地渲染 Lottie 动画，同时提供方式获取到全局 Lottie 和动画实例满足更广泛的配置需求。内部基于 lottie-web 渲染 Lottie 动画。
相较于直接使用 lottie-web，使用 Semi Lottie 组件的优势在于

无需关心动画容器的创建与销毁
无需关心动画本身的生命周期

更易和 Vue 项目结合使用

代码演示

如何引入

<script setup lang="ts">
    import { Lottie } from '@fibrous/semi-ui-vue';
</script>

基本用法

当 Lottie 动画资源 JSON 在 CDN 上时

向 params props 里传入 path= 你的 lottie json 的 URL 即可

代码

<script setup lang="ts">
    import { Lottie } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" />
    </div>
</template>

当 Lottie 动画资源 JSON 需要被打包到网站代码中时

向 params props 里传入 animationData= 你的 lottie json 对象即可 (下方 Demo 请求 JSON 是仅作为演示，实际项目中 json 应当被手动 import，而不是通过网络请求获取，这样 JSON 动画资源才会被打包进网站代码)

代码

<script setup lang="ts">
    import { computed, onMounted, shallowRef } from 'vue';
    import { Lottie } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';

    // large animation data is held in a shallowRef so it is not made deeply reactive
    const data = shallowRef<object | string>('');
    // params reloads the animation when it is replaced, so it is derived from the data instead of mutated
    const params = computed(() => ({ animationData: data.value }));

    onMounted(() => {
        void fetch(jsonURL)
            .then((resp) => resp.json())
            .then((json: object) => {
                data.value = json;
            });
    });
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" />
    </div>
</template>

Params 其他常用参数

params 会被组件传入 lottie-web 的 lottie.loadAnimation 中，可以参考 lottie-web 文档

常用参数

//params
{
    container: element, // 渲染容器，不传则由 Semi Lottie 组件自动配置并生成
    renderer: 'svg', // 渲染方式， 默认 SVG
    loop: true, // 是否开启循环，默认 true
    autoplay: true, // 是否自动播放，默认 true，设置为 false 时需要通过动画实例上的 play 方法手动播放
    path: 'data.json' // 动画 JSON 文件的 URL 路径 （与 animationData 互斥）
    animationData: {/*...*/} // 动画的 JSON 对象 （与 animationData 互斥）
    /*...*/
}

获取当前动画实例

监听 @getAnimationInstance 事件获取当前播放的动画的 animation 实例，实例上含有许多方法用于调整动画的各项参数，例如播放暂停，获取当前帧序号，调整播放速度等。每创建一次动画（包括每次重新加载）触发一次，载荷类型为 AnimationItem，不会是 null。

关于动画实例上含有的方法，更多信息可以参考 lottie-web 文档

代码

<script setup lang="ts">
    import { Lottie, type LottieAnimation } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };

    const onAnimation = (animation: LottieAnimation) => {
        console.log(animation);
    };
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" @getAnimationInstance="onAnimation" />
    </div>
</template>

获取全局 Lottie

监听 @getLottie 事件获取全局 lottie，也可以使用 Semi Lottie 组件上的静态方法 Lottie.getLottie 来获取全局 lottie

lottie-web 体积较大，Semi 在需要创建动画时才按需加载它：getLottie 事件在加载完成、动画创建后触发，每次挂载只触发一次；静态方法 Lottie.getLottie() 是异步的，返回解析为 lottie 的 Promise（需要使用 await 或 .then）。加载完成前组件不渲染动画；卸载时若尚未加载完成，则不会再创建动画。

关于全局 lottie 上含有的方法，更多信息可以参考 lottie-web 文档

代码

<script setup lang="ts">
    import { onMounted } from 'vue';
    import { Lottie, type LottieModule } from '@fibrous/semi-ui-vue';

    const jsonURL = '/assets/root-web-sites/lottie_demo.json';
    const params = { path: jsonURL };

    const onLottie = (lottie: LottieModule) => {
        console.log('lottie', lottie);
    };

    onMounted(() => {
        void Lottie.getLottie().then((lottie) => console.log('lottie', lottie));
    });
</script>

<template>
    <div>
        <Lottie height="300px" :params="params" width="300px" @getLottie="onLottie" />
    </div>
</template>

API

Props

属性	说明	类型	默认值
params	传给 lottie-web loadAnimation 的参数。内容变化时重新加载，原地修改不会触发：请整体替换，较大的动画数据用 shallowRef 持有。	`Type`	`undefined`
width	容器宽度，需带单位，如 300px。	`string`	`semiGlobalDefault("Lottie", "width")`
height	容器高度，需带单位，如 300px。	`string`	`semiGlobalDefault("Lottie", "height")`

Events

事件	说明	回调参数
getAnimationInstance	每创建一次动画（包括每次重新加载）触发一次，载荷为当前动画的 AnimationItem。	`[animation: LottieAnimation]`
getLottie	lottie-web 加载完成后，每次挂载触发一次，载荷为全局 Lottie。	`[lottie: LottieModule]`

Slots

插槽	说明	作用域参数
无

Exposes

名称	说明	类型
无

class、style 与原生属性经 attrs 落在容器元素上。params 按引用变化加深比较决定是否重新加载：父级每次渲染传新的字面量不会重载，整体替换为不同内容才会重载，原地修改 params 不会重载。较大的动画数据用 shallowRef 或 markRaw 持有，组件传给 lottie-web 的是原始对象。params.container 存在时组件只渲染一个注释节点，$el 是该注释，attrs 被丢弃。

静态方法

方法	说明	类型
`Lottie.getLottie`	异步获取全局 Lottie，首次调用时才加载 `lottie-web`	() => Promise<Lottie>

Accessibility

传入 aria-label 或 aria-labelledby 的动画是带名称的图像，容器带 role="img"；没有名称的动画是装饰，容器带 aria-hidden="true"。使用方传入的 role 与 aria-* 优先
系统开启 prefers-reduced-motion: reduce 时动画不自动播放，运行中系统设置变化时会随之暂停或播放；params.autoplay 显式设置时以它为准