frontend-lottie

用途

frontend-lottie 是一个面向前端 UI 的 Lottie 动画技能，用于为界面添加装饰性 JSON 矢量动画，提供视觉反馈与细节润色。它定位为轻量级动画方案：只负责播放和循环，不包含复杂逻辑。

主要能力

该技能覆盖以下动画用途：

加载旋转指示器（loading spinners）
成功/错误对勾反馈（success/error checkmarks）
空状态插画（empty state illustrations）
装饰性微动画（decorative micro-animations）
动画图标（animated icons）

使用方式

整体流程为 FIND → ADD → INTEGRATE：

寻找动画：可从 https://lottiefiles.com 等资源站获取。
下载 .lottie 或 .json 文件。
放入 public/animations/ 目录。
使用组件集成。

安装命令：

npm install @lottiefiles/dotlottie-react

基础用法示例：

import { DotLottieReact } from '@lottiefiles/dotlottie-react';

// Simple autoplay
<DotLottieReact
  src="/animations/loading.lottie"
  autoplay
  loop
  style={{ width: 200, height: 200 }}
/>

常见模式包括：

// Loading spinner
<DotLottieReact src="/spinner.lottie" autoplay loop style={{ width: 48 }} />

// Success feedback (plays once)
<DotLottieReact src="/success.lottie" autoplay loop={false} />

// Empty state
<div className="flex flex-col items-center py-16">
  <DotLottieReact src="/empty.lottie" autoplay loop style={{ width: 200 }} />
  <h3>No results found</h3>
</div>

// Loading button
{isLoading ? (
  <DotLottieReact src="/button-loader.lottie" autoplay loop style={{ width: 24 }} />
) : (
  "Submit"
)}

播放控制可通过 dotLottieRefCallback 获取实例，支持的方法有 play()、pause()、stop()、setSpeed(n)、goToAndPlay(frame)。示例：

'use client'
import { useState, useCallback } from 'react'
import { DotLottieReact, DotLottie } from '@lottiefiles/dotlottie-react'

function ControlledLottie() {
  const [dotLottie, setDotLottie] = useState<DotLottie | null>(null)

  return (
    <div
      onMouseEnter={() => dotLottie?.play()}
      onMouseLeave={() => dotLottie?.pause()}
    >
      <DotLottieReact
        src="/animation.lottie"
        loop
        dotLottieRefCallback={setDotLottie}
      />
    </div>
  )
}

SSR 与 hydration 处理：始终添加 'use client'，或使用动态导入并设置 ssr: false，或进行 mounted 检查：

'use client'

const DotLottieReact = dynamic(
  () => import('@lottiefiles/dotlottie-react').then(m => m.DotLottieReact),
  { ssr: false }
)

const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
if (!mounted) return <Skeleton />

性能优化：可在元素不可见时暂停动画，例如结合 react-intersection-observer：

import { useInView } from 'react-intersection-observer'

const { ref, inView } = useInView({ threshold: 0.1 })

useEffect(() => {
  inView ? dotLottie?.play() : dotLottie?.pause()
}, [inView, dotLottie])

建议的文件结构：

public/animations/
  loaders/spinner.lottie
  feedback/success.lottie, error.lottie
  empty-states/no-data.lottie
  illustrations/hero.lottie

适用场景

适合只需要播放/循环的简单动画场景，例如加载指示、一次性成功反馈、空状态展示、按钮内加载状态、装饰性图标等。

限制与不适用场景

当动画需要响应输入（如 hover/click 触发状态变化）、包含多个状态/过渡、或需要复杂交互与数据驱动时，应改用 Rive。技能中给出的判断标准为：仅播放/循环用 Lottie；响应 hover/click、状态机、数据驱动用 Rive；简单加载器用 Lottie。

故障排查

动画未加载：检查 public/ 中的文件路径，确认 .lottie 或 .json 扩展名。
动画未播放：添加 autoplay={true} 和 loop={true}。
Hydration 不匹配：添加 'use client'，或使用 dynamic(() => ..., { ssr: false })。
速度过快/过慢：speed={0.5} 变慢，speed={2} 变快。

参考资源

patterns.md — 受控播放、事件、可见性暂停、hover/click 触发
https://lottiefiles.com/free-animations — 免费动画
https://useanimations.com — 微交互
https://lordicon.com — 动画图标
最新 API 可参考 context7 技能