名称: auto-animate 描述: AutoAnimate (@formkit/auto-animate) 是一个零配置的动画库，适用于 React。用于列表过渡、手风琴、提示消息，或处理 SSR 错误、动画库复杂性。

关键词: auto-animate, @formkit/auto-animate, formkit, 零配置动画, 自动动画, 即插即用动画, 列表动画, 手风琴动画, 提示消息动画, 表单验证动画, 轻量级动画, 2kb 动画, 偏好减少运动, 可访问动画, vite react 动画, cloudflare workers 动画, ssr 安全动画许可证: MIT

AutoAnimate

状态: 生产就绪 ✅ 最后更新: 2025-11-07 依赖: 无（适用于任何 React 设置） 最新版本: @formkit/auto-animate@0.9.0

快速开始（2 分钟）

1. 安装 AutoAnimate

bun add @formkit/auto-animate

重要性:

仅 3.28 KB 压缩（相比 Motion 的 22 KB）
零依赖
框架无关（React, Vue, Svelte, 原生 JS）

2. 添加到组件

import { useAutoAnimate } from "@formkit/auto-animate/react";

export function MyList() {
  const [parent] = useAutoAnimate(); // 1. 获取引用

  return (
    <ul ref={parent}> {/* 2. 附加到父元素 */}
      {items.map(item => (
        <li key={item.id}>{item.text}</li> {/* 3. 完成！ */}
      ))}
    </ul>
  );
}

关键:

✅ 始终为列表项使用唯一、稳定的键
✅ 父元素必须始终渲染（非条件性）
✅ AutoAnimate 自动尊重 prefers-reduced-motion
✅ 适用于添加、删除和重新排序操作

3. 在生产中使用（SSR 安全）

对于 Cloudflare Workers 或 Next.js：

// 使用仅客户端导入以防止 SSR 错误
import { useState, useEffect } from "react";

export function useAutoAnimateSafe<T extends HTMLElement>() {
  const [parent, setParent] = useState<T | null>(null);

  useEffect(() => {
    if (typeof window !== "undefined" && parent) {
      import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
        autoAnimate(parent);
      });
    }
  }, [parent]);

  return [parent, setParent] as const;
}

已知问题预防

此技能预防 10+ 个文档化问题：

问题 #1: SSR/Next.js 导入错误

错误: “无法从非 ECMAScript 模块导入命名导出 ‘useEffect’” 来源: https://github.com/formkit/auto-animate/issues/55 原因: AutoAnimate 使用服务器不可用的 DOM API 预防: 使用动态导入（见 templates/vite-ssr-safe.tsx）

问题 #2: 条件性父元素渲染

错误: 父元素条件性时动画不工作来源: https://github.com/formkit/auto-animate/issues/8 原因: 引用无法附加到不存在的元素预防:

// ❌ 错误
{showList && <ul ref={parent}>...</ul>}

// ✅ 正确
<ul ref={parent}>{showList && items.map(...)}</ul>

问题 #3: 缺少唯一键

错误: 项目动画不正确或闪烁来源: 官方文档原因: React 无法跟踪哪些项目已更改预防: 始终使用唯一、稳定的键（key={item.id}）

问题 #4: Flexbox 宽度问题

错误: 元素跳转到宽度而不是平滑动画来源: 官方文档原因: flex-grow: 1 等待周围内容预防: 为动画元素使用显式宽度而不是 flex-grow

问题 #5: 表格行显示问题

错误: 删除行时表格结构损坏来源: https://github.com/formkit/auto-animate/issues/7 原因: Display: table-row 与动画冲突预防: 应用于 <tbody> 而不是单独行，或使用基于 div 的布局

问题 #6: Jest 测试错误

错误: “无法找到模块 ‘@formkit/auto-animate/react’” 来源: https://github.com/formkit/auto-animate/issues/29 原因: Jest 未正确解析 ESM 导出预防: 在 jest.config.js 中配置 moduleNameMapper

问题 #7: esbuild 兼容性

错误: “路径 ‘.’ 未被包导出” 来源: https://github.com/formkit/auto-animate/issues/36 原因: ESM/CommonJS 条件不匹配预防: 配置 esbuild 正确处理 ESM 模块

问题 #8: CSS 位置副作用

错误: 添加 AutoAnimate 后布局损坏来源: 官方文档原因: 父元素自动获取 position: relative 预防: 在 CSS 中考虑位置变化或显式设置

问题 #9: Vue/Nuxt 注册错误

错误: “无法解析指令: auto-animate” 来源: https://github.com/formkit/auto-animate/issues/43 原因: 插件未正确注册预防: Vue/Nuxt 配置中的适当插件设置（见 references/）

问题 #10: Angular ESM 问题

错误: 构建失败，显示“仅 ESM 包” 来源: https://github.com/formkit/auto-animate/issues/72 原因: CommonJS 构建环境预防: 为 Angular 包格式配置 ng-packagr

何时使用 AutoAnimate vs Motion

使用 AutoAnimate 当：

✅ 简单列表过渡（添加/删除/排序）
✅ 手风琴展开/折叠
✅ 提示消息淡入/淡出
✅ 表单验证消息出现/消失
✅ 偏好零配置
✅ 小包大小关键（3.28 KB）
✅ 应用于现有/第三方代码
✅ “足够好”动画可接受

使用 Motion 当：

✅ 复杂编排动画
✅ 手势控制（拖拽、滑动、悬停）
✅ 基于滚动的动画
✅ 弹簧物理动画
✅ SVG 路径动画
✅ 需要关键帧控制
✅ 动画变体/编排
✅ 自定义缓动曲线

经验法则: 90% 的情况使用 AutoAnimate，英雄/交互式动画使用 Motion。

关键规则

始终做

✅ 使用唯一、稳定的键 - key={item.id} 而非 key={index} ✅ 保持父元素在 DOM 中 - 父引用元素始终渲染 ✅ 仅客户端用于 SSR - 服务器环境使用动态导入 ✅ 尊重可访问性 - 保持 disrespectUserMotionPreference: false ✅ 禁用动画测试 - 验证 UI 在无动画时工作 ✅ 使用显式宽度 - 避免在动画元素上使用 flex-grow ✅ 应用于 tbody 以用于表格 - 非单独行

永远不做

❌ 条件性父元素 - {show && <ul ref={parent}>} ❌ 索引作为键 - key={index} 破坏动画 ❌ 忽略 SSR - 在 Cloudflare Workers/Next.js 中会损坏 ❌ 强制动画 - disrespectUserMotionPreference: true 破坏可访问性 ❌ 直接动画表格 - 使用 tbody 或基于 div 的布局 ❌ 跳过唯一键 - 适当动画所需 ❌ 复杂动画 - 使用 Motion 代替

配置

AutoAnimate 默认零配置。可选自定义：

import { useAutoAnimate } from "@formkit/auto-animate/react";

const [parent] = useAutoAnimate({
  duration: 250, // 毫秒（默认: 250）
  easing: "ease-in-out", // CSS 缓动（默认: "ease-in-out"）
  // disrespectUserMotionPreference: false, // 保持 false！
});

推荐: 除非有特定设计需求，否则使用默认值。

使用捆绑资源

模板 (templates/)

复制粘贴就绪示例：

react-basic.tsx - 带添加/删除/洗牌的简单列表
react-typescript.tsx - 带自定义配置的键入设置
filter-sort-list.tsx - 动画过滤和排序
accordion.tsx - 可展开部分
toast-notifications.tsx - 淡入/淡出消息
form-validation.tsx - 错误消息动画
vite-ssr-safe.tsx - Cloudflare Workers/SSR 模式

参考 (references/)

auto-animate-vs-motion.md - 决策指南，选择哪个使用
css-conflicts.md - Flexbox、表格和位置陷阱
ssr-patterns.md - Next.js、Nuxt、Workers 变通方案

脚本 (scripts/)

init-auto-animate.sh - 自动化设置脚本

Cloudflare Workers 兼容性

AutoAnimate 完美适用于 Cloudflare Workers 静态资产：

✅ 仅客户端 - 在浏览器中运行，非 Worker 运行时 ✅ 无 Node.js 依赖 - 纯浏览器代码 ✅ 边缘友好 - 3.28 KB 压缩 ✅ SSR 安全 - 使用动态导入（见 templates/）

Vite 配置:

export default defineConfig({
  plugins: [react(), cloudflare()],
  ssr: {
    external: ["@formkit/auto-animate"],
  },
});

可访问性

AutoAnimate 自动尊重 prefers-reduced-motion：

/* 用户系统偏好 */
@media (prefers-reduced-motion: reduce) {
  /* AutoAnimate 自动禁用动画 */
}

关键: 永远不设置 disrespectUserMotionPreference: true - 这会破坏可访问性。

官方文档

官方网站: https://auto-animate.formkit.com
GitHub: https://github.com/formkit/auto-animate
npm: https://www.npmjs.com/package/@formkit/auto-animate
React 文档: https://auto-animate.formkit.com/react
视频教程: Laracasts 视频（见 README）

包版本（已验证 2025-11-07）

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  },
  "devDependencies": {
    "react": "^19.2.0",
    "vite": "^6.0.0"
  }
}

生产示例

此技能基于生产测试：

包大小: 3.28 KB 压缩
设置时间: 2 分钟（相比 Motion 的 15 分钟）
错误: 0（所有 10 个已知问题预防）
验证: ✅ 适用于 Vite, Tailwind v4, Cloudflare Workers, React 19

测试场景:

✅ 过滤/排序列表
✅ 手风琴组件
✅ 提示消息
✅ 表单验证消息
✅ SSR/Cloudflare Workers
✅ 可访问性（偏好减少运动）

故障排除

问题: 动画不工作

解决方案: 检查这些常见问题：

父元素是否始终在 DOM 中？（非条件性）
项目是否有唯一、稳定的键？
引用是否附加到动画子元素的直接父元素？

问题: SSR/Next.js 错误

解决方案: 使用动态导入：

useEffect(() => {
  if (typeof window !== "undefined") {
    import("@formkit/auto-animate").then(({ default: autoAnimate }) => {
      autoAnimate(parent);
    });
  }
}, [parent]);

问题: 项目闪烁而非动画

解决方案: 添加唯一键：key={item.id} 而非 key={index}

问题: Flexbox 宽度问题

解决方案: 使用显式宽度而不是 flex-grow: 1

问题: 表格行不动画

解决方案: 将引用应用于 <tbody>，而非单独 <tr> 元素

完整设置清单

[ ] 已安装 @formkit/auto-animate@0.9.0
[ ] 使用 React 19+（或 Vue/Svelte）
[ ] 添加引用到父元素
[ ] 父元素始终渲染（非条件性）
[ ] 列表项有唯一、稳定的键
[ ] 用 prefers-reduced-motion 测试
[ ] 如果使用 Cloudflare Workers/Next.js，则 SSR 安全
[ ] 无 Flexbox 宽度问题
[ ] 开发服务器运行无错误
[ ] 生产构建成功

问题？问题？

检查 templates/ 查看工作示例
检查 references/auto-animate-vs-motion.md 查看库比较
检查 references/ssr-patterns.md 查看 SSR 变通方案
检查官方文档: https://auto-animate.formkit.com
检查 GitHub 问题: https://github.com/formkit/auto-animate/issues

生产就绪？ ✅ 是 - 13.6k 星，积极维护，零依赖。