# AutoAnimate - 错误预防指南 **软件包**：@formkit/auto-animate@0.9.0（2025 年 9 月）**框架**：React、Vue、Solid、Svelte、Preact **最后更新**：2025 年 11 月 22 日 ** ** ## SSR 安全模式（对于 Cloudflare Workers/Next.js 至关重要） // 使用仅客户端导入来防止 SSR 错误从“react”导入{ useState，useEffect }；导出函数 useAutoAnimateSafe() { const [父级，setParent] = useState(空); 使用效果（（）=> { if（窗口类型！==“未定义”&&父）{ import("@formkit/auto-animate").then(({ 默认值：autoAnimate }) => { 自动动画（父级）； }); } }, [父]); 将 [parent, setParent] 返回为 const； } **为什么这很重要**：防止问题#1（SSR/Next.js 导入错误）。 AutoAnimate 使用服务器上不可用的 DOM API。 ** ** ## 已知问题预防（10 个已记录的错误）此技能可防止 **10+** 记录的问题： ### 问题 #1：SSR/Next.js 导入错误 **错误**：“无法从非 EcmaScript 模块导入命名导出“useEffect”” **来源**： **为什么会发生**：AutoAnimate 使用服务器上不可用的 DOM API **预防**：使用动态导入（请参阅 `templates/vite-ssr-safe.tsx`） ### 问题#2：条件父级渲染 **错误**：当父级有条件时，动画不起作用 **来源**： **为什么会发生**：引用无法附加到不存在的元素 **预防**： // ❌ 错误 {showList &&

...} // ✅ 正确

{showList && items.map(...)} ### 问题#3：缺少唯一键 **错误**：项目没有正确动画或闪烁 **来源**：官方文档 **为什么会发生**：React 无法跟踪哪些项目发生了变化 **预防**：始终使用唯一、稳定的密钥 (`key={item.id}`) ### 问题#4：Flexbox 宽度问题 **错误**：元素对齐宽度而不是平滑地动画 **来源**：官方文档 **为什么会发生**：`flex-grow: 1` 等待周围的内容 **预防**：对动画元素使用显式宽度而不是 flex-grow ### 问题 #5：表格行显示问题 **错误**：删除行时表结构中断 **来源**： **为什么会发生**：显示：表行与动画冲突 **预防**：应用于``而不是单个行，或使用基于 div 的布局 ### 问题#6：玩笑测试错误 **错误**：“找不到模块'@formkit/auto-animate/react'” **来源**： **为什么会发生**：Jest无法正确解析ESM导出 **预防**：在jest.config.js中配置`moduleNameMapper` ### 问题 #7：esbuild 兼容性 **错误**：“路径‘.’未由包导出” **来源**： **为什么会发生**：ESM/CommonJS 条件不匹配 **预防**：配置 esbuild 以正确处理 ESM 模块 ### 问题 #8：CSS 位置副作用 **错误**：添加 AutoAnimate 后布局中断 **来源**：官方文档 **为什么会发生**：父项自动获取 `position:relative` **预防**：考虑 CSS 中的位置更改或显式设置 ### 问题 #9：Vue/Nuxt 注册错误 **错误**：“无法解析指令：自动动画” **来源**： **为什么会发生**：插件未正确注册 **预防**：Vue/Nuxt 配置中正确的插件设置（请参阅参考资料/） ### 问题 #10：Angular ESM 问题 **错误**：构建因“仅 ESM 包”而失败 **来源**： **为什么会发生**：CommonJS 构建环境 **预防**：为 Angular 包格式配置 ng-packagr ** ** ## 关键规则（错误预防） ### 总是这样做 ✅ **使用唯一、稳定的键** \- `key={item.id}` 而不是 `key={index}` ✅ **将父级保留在 DOM 中** \- 始终呈现父级 ref 元素 ✅ **仅适用于 SSR** \- 服务器环境的动态导入 ✅ **尊重可访问性** \- 保持 `disrespectUserMotionPreference: false` ✅ **禁用运动测试** \- 验证 UI 在没有动画的情况下是否正常工作 ✅ **使用显式宽度** \- 避免 flex-grow动画元素 ✅ **应用于表格的主体** \- 不是单独的行 ### 永远不要这样做 ❌ **条件父级** \- `{show &&

* **GitHub**： * **npm** ： * **React 文档**： ** ** ## 模板和参考查看捆绑资源： * `templates/` \- 复制粘贴示例（SSR 安全、手风琴、吐司、表单） * `references/` \- CSS 冲突、SSR 模式、库比较

自动动画

包含技能