auto-animate

AutoAnimate - 错误预防指南

软件包：@formkit/[email protected]（2025 年 9 月） 框架：React、Vue、Solid、Svelte、Preact 最后更新：2025-11-22

---

SSR 安全模式（对 Cloudflare Workers/Next.js 至关重要）

// Use client-only import to prevent SSR errors
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;
}

重要原因：预防问题 #1（SSR/Next.js 导入错误）。AutoAnimate 使用了服务器上不可用的 DOM API。

---

已知问题预防（10 个已记录的错误）

此技能可预防 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 原因：ref 无法附加到不存在的元素上 预防方法：

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

// ✅ Correct
<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 Package Format 配置 ng-packagr

---

关键规则（错误预防）

务必做到

✅ 使用唯一且稳定的键 - 使用 key={item.id}，而不是 key={index} ✅ 让父元素保留在 DOM 中 - 父元素 ref 始终处于渲染状态 ✅ SSR 环境仅在客户端运行 - 在服务器环境中使用动态导入 ✅ 遵循无障碍要求 - 保持 disrespectUserMotionPreference: false ✅ 在关闭动画时进行测试 - 确认 UI 在没有动画时仍可正常运行 ✅ 使用明确指定的宽度 - 避免在动画元素上使用 flex-grow ✅ 对表格应用于 tbody - 不要应用于单独的行

切勿这样做

❌ 有条件的父元素 - {show && <ul ref={parent}>} ❌ 将索引用作键 - key={index} 会破坏动画 ❌ 忽略 SSR - 会导致 Cloudflare Workers/Next.js 出错 ❌ 强制播放动画 - disrespectUserMotionPreference: true 会影响无障碍访问 ❌ 直接为表格添加动画 - 使用 tbody 或基于 div 的布局 ❌ 省略唯一键 - 正确播放动画所必需 ❌ 使用复杂动画 - 改用 Motion

注意：AutoAnimate 会自动遵循 prefers-reduced-motion（切勿禁用此功能）。

---

软件包版本

最新版本：@formkit/[email protected]（2025 年 9 月 5 日）

{
  "dependencies": {
    "@formkit/auto-animate": "^0.9.0"
  }
}

框架兼容性：React 18+、Vue 3+、Solid、Svelte、Preact

---

官方文档

• 官方网站：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

---

模板与参考资料

请参阅随附资源：

• templates/ - 可复制粘贴的示例（兼容 SSR、手风琴、提示消息、表单）
• references/ - CSS 冲突、SSR 模式、库对比