前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载Semi Design 在 v2.62.0 起提供内置Lottie组件它基于lottie-web封装让开发者无需关心动画容器的创建与销毁、动画本身的生命周期管理即可在 React 项目中便捷渲染 Lottie 动画。本文围绕官方文档content/plus/lottie/index-en-US.md讲解完整使用方式从 CDN 加载与资源打包两种引入模式、params全部常用配置项到获取动画实例与全局 Lottie 进行精细控制并结合 semi-ui/lottie 与 semi-foundation/lottie 的源码剖析其内部实现原理帮你写出可复制、可维护的 Lottie 动画代码。使用场景与设计动机Lottie 动画文件由设计师通过 After Effects 等工具导出为 JSON体积小、矢量缩放不模糊广泛用于加载提示、空状态、交互动效等场景。Semi Design 的 Lottie 组件封装了lottie-web使动画渲染更简单可控相比直接使用lottie-web具有三点核心优势无需关心动画容器的创建与销毁组件内部自动生成渲染容器组件卸载时自动销毁动画实例无需关心动画本身的生命周期挂载初始化、params变更重建、卸载销毁均由组件与 Foundation 层接管更易与 React 项目结合使用以声明式 props 接入支持受控的尺寸、样式与回调。快速上手引入与版本要求Lottie 组件从v2.62.0开始支持从douyinfe/semi-ui顶层直接导入即可import { Lottie } from douyinfe/semi-ui;在 packages/semi-ui/index.ts 中可以看到Lottie与其他组件一起被统一导出export { default as Lottie } from ./lottie其组件实现位于 packages/semi-ui/lottie/index.tsx底层依赖lottie-webpackages/semi-foundation/package.json 中声明为lottie-web: ^5.13.0由 semi-foundation 的LottieFoundation负责核心逻辑。基本用法两种动画资源加载方式根据动画 JSON 资源的存放位置Lottie支持两种加载模式二者通过params中的path与animationData区分二者互斥。模式一动画 JSON 位于 CDN当动画资源通过 URL 提供时将path属性传入paramsimport { Lottie } from douyinfe/semi-ui; import React from react; () { const jsonURL https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/lottie_demo.json; return ( div Lottie params{{ path: jsonURL }} width{300px} height{300px} / /div ); };该模式下lottie-web会通过网络请求加载 JSON适合动画资源独立部署、可被多个站点复用的场景如统一动效 CDN。模式二动画 JSON 打包进网站代码当动画资源需要随前端工程一起打包时将 JSON 对象传入animationDataimport { Lottie } from douyinfe/semi-ui; import React from react; () { const jsonURL https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/lottie_demo.json; const [data, setData] useState(); useEffect(() { fetch(jsonURL) .then(resp resp.json()) .then(setData); }, []); return ( div Lottie params{{ animationData: data }} width{300px} height{300px} / /div ); };注意上面 Demo 中通过fetch请求 JSON 仅用于演示。实际项目中应使用import animationData from ./lottie.json手动导入这样动画 JSON 才会被 Webpack/Rspack/Vite 等构建工具识别并打包进网站代码避免运行时依赖网络请求。params 参数详解params会被组件原样透传给lottie-web的lottie.loadAnimation官方文档中的参数说明与lottie-web的loadAnimation入参保持一致。常用参数如下// params { container: element, // 渲染容器不传则由 Semi Lottie 组件自动配置并生成 renderer: svg, // 渲染方式默认 SVG loop: true, // 是否开启循环默认 true autoplay: true, // 是否自动播放默认 true设置为 false 时需要手动调用动画实例的 play 方法 path: data.json, // 动画 JSON 文件的 URL 路径与 animationData 互斥 animationData: {/*...*/}, // 动画的 JSON 对象与 path 互斥 /*...*/ }各字段含义与取值建议参数类型默认值说明containerElement组件自动生成渲染容器。传入后组件不再自行渲染包裹 div见下文源码解析rendererstringsvg渲染方式svg/canvas/htmlSemi 默认使用 SVGloopboolean/numbertrue是否循环播放也可传入数字指定循环次数autoplaybooleantrue是否自动播放设为false时需通过动画实例的play()手动播放pathstring-动画 JSON 的 URL与animationData互斥animationDataobject-动画 JSON 对象与path互斥源码视角默认值如何合并从 packages/semi-ui/lottie/index.tsx 的getLoadParams实现可以看到组件并非直接透传params而是先设置container、renderer: svg、loop: true、autoplay: true四个默认值再通过对象展开...this.props.params覆盖它们getLoadParams: () { return { container: getContainer(), renderer: svg, loop: true, autoplay: true, ...this.props.params, }; }这意味着即使你不传任何参数组件也能以SVG 渲染 循环 自动播放的方式直接运行而传入params中的值会精确覆盖默认配置。源码视角容器如何自动管理在 packages/semi-ui/lottie/index.tsx 的render中有一个关键分支if (this.props.params.container) { return null; } else { return div ref{this.container} style{this.wrapperStyle} className{this.wrapperClassName} /; }若你在params中提供了container组件不会渲染额外的包装元素动画直接渲染到你指定的容器里若未提供组件自动渲染一个div作为容器并通过getContainerindex.tsx#L50-L52优先返回props.params.container、否则返回内部this.container.current。宽度与高度通过width/heightprops 以wrapperStyle的形式作用到这个自动生成的容器上index.tsx#L79-L85这也是为什么文档示例中width、height需要以300px这样的字符串形式传入。获取当前动画实例精细控制播放getAnimationInstance回调会在动画加载完成后收到当前AnimationItem实例。实例上提供了丰富的控制方法例如播放、暂停、获取当前帧序号、调整播放速度等import { Lottie } from douyinfe/semi-ui; import React from react; () { const jsonURL https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/lottie_demo.json; return ( div Lottie getAnimationInstance{animation { console.log(animation); }} params{{ path: jsonURL }} width{300px} height{300px} / /div ); };拿到实例后即可调用animation.play()、animation.pause()、animation.goToAndStop(frame, true)、animation.setSpeed(speed)、animation.currentFrame等lottie-web的AnimationItem方法。结合autoplay: false你可以在加载完成后按需手动触发播放。源码视角实例回调的触发时机getAnimationInstance在三个时机被触发packages/semi-foundation/lottie/foundation.tsinit()组件挂载后调用lottie.loadAnimation创建实例并立即回调handleParamsUpdate()params内容变化时先destroy()旧实例再重建新实例并回调另外 index.tsx#L68-L71 的componentDidMount中也会通过this.foundation.animation回调一次且组件通过isEquallodash深度比较prevProps.params与this.props.paramsindex.tsx#L73-L77来判定是否触发重建因此即使params对象是每次渲染新建的只要内容相同也不会反复销毁重建动画。获取全局 Lottie 对象lottie-web除了loadAnimation外还暴露全局方法如registerAnimation、destroy等。Semi Lottie 提供两种方式获取全局 lottie方式一通过getLottieprops 回调import { Lottie } from douyinfe/semi-ui; import React from react; () { const jsonURL https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/lottie_demo.json; console.log(lottie, Lottie.getLottie()); return ( div Lottie getLottie{lottie console.log(lottie, lottie)} params{{ path: jsonURL }} width{300px} height{300px} / /div ); };方式二通过静态方法Lottie.getLottie()在组件类上直接调用Lottie.getLottie()即可无需先渲染组件。其实现非常轻量——直接返回lottie-web模块本身packages/semi-foundation/lottie/foundation.ts#L33-L35在 packages/semi-ui/lottie/index.tsx#L35 中以静态属性static getLottie LottieFoundation.getLottie暴露给组件使用者。组件 API 总览属性说明类型默认值className类名string-params用于配置动画相关参数同lottie-web的lottie.loadAnimation入参-getAnimationInstance获取当前动画AnimationItem(animation: AnimationItem) void-getLottie获取全局 Lottie(lottie: Lottie) void-style样式CSSProperties-另有width、height两个非文档主表但示例中高频使用的属性用于控制自动生成容器的尺寸。className会被拼接到semi-lottie前缀类名之后cssClasses.PREFIX定义于 packages/semi-foundation/lottie/constants.ts。生命周期与销毁机制源码级工作原理Semi Lottie 组件采用「组件 Foundation」的分层结构组件层packages/semi-ui/lottie/index.tsx负责 DOM 与 React 生命周期Foundation 层packages/semi-foundation/lottie/foundation.ts负责动画实例的创建、更新与销毁挂载组件componentDidMount触发 Foundation 的init()内部执行lottie.loadAnimation(this._adapter.getLoadParams())创建动画实例并依次触发getAnimationInstance与getLottie回调foundation.ts#L37-L42更新params变化时handleParamsUpdate先调用旧实例的destroy()释放资源再以新参数重建实例foundation.ts#L44-L48卸载Foundation 的destroy()中调用this.animation.destroy()彻底销毁动画避免内存泄漏与残留渲染foundation.ts#L50-L53。这套封装正是文档所说无需关心动画容器的创建与销毁、无需关心动画本身的生命周期的底层来源容器由组件自动生成实例的创建、重建、销毁全部由 Foundation 统一调度使用方只需声明式地描述要渲染哪个动画、以什么参数渲染。实战建议与注意事项优先使用animationData 静态 import将 JSON 打包进产物可减少运行时网络请求且便于构建工具做体积分析与缓存CDNpath模式适合多站点复用同一动效资源的场景。动态切换动画直接更新params如切换path或animationData即可组件会基于深度比较自动销毁旧实例并加载新动画无需手动管理。需要手动控制播放时设置params.autoplay: false并通过getAnimationInstance拿到的实例调用play()、pause()、goToAndStop()、setSpeed()等方法。自定义渲染容器若动画需要嵌入特定 DOM 结构可在params.container中传入既有元素此时组件不会额外渲染包装节点。在 v2.62.0 之前的版本中不存在该组件使用前请确认douyinfe/semi-ui的版本满足要求动画参数明细如渲染器能力差异、实例完整方法列表以lottie-web官方说明为准。赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design.‍ Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐Semi Design Lottie 组件完全指南在 React 中渲染与掌控 Lottie 动画Semi Design Lottie 组件完全指南在 React 中渲染与掌控 Lottie 动画 Semi Design 在 douyinfe/semi前端UI组件设计系统Semi Design 中的 Lottie 动画组件详解Semi Design 中的 Lottie 动画组件详解 什么是 Lottie 动画 Lottie 是一种基于 JSON 格式的矢量动画解决方案由 Airb前端UI组件设计系统wp-calypso 中的 AnimatedIcon 组件基于 Lottie 的 After Effects 动画渲染实战指南wp calypso 中的 AnimatedIcon 组件基于 Lottie 的 After Effects 动画渲染实战指南 AnimatedIcon /前端CMS上一篇CANN/ge开发者工具链指南下一篇Nodeclub数据库连接复用减少MongoDB连接开销创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考