auto-animate

AutoAnimate 技能为前端开发者提供了一套基于 @formkit/auto-animate 的零配置动画解决方案，专注于列表重排、手风琴展开、Toast 通知等常见 UI 动效场景。该技能的核心价值在于不仅提供了极简的 API 调用方式（仅需一行代码即可为容器添加智能动画），更重要的是系统性地总结了 15 个官方 GitHub Issues 中记录的高频错误，包括 React 19 StrictMode 双调用 Bug、Next.js/Cloudflare Workers 的 SSR 导入错误、Flexbox 容器抖动、条件渲染父元素失效等，并提供了对应的预防代码模板。

该方案的显著优势在于其极低的接入成本与多框架兼容性。作为仅 3.28kb 的轻量库，它支持 React、Vue、Solid、Svelte 和 Preact，且内置了对 prefers-reduced-motion 的自动响应，确保可访问性合规。技能中提供的 SSR-Safe Pattern 通过动态导入（dynamic import）结合 typeof window 判断，彻底解决了服务端渲染环境下的 DOM API 报错问题，这对于使用 Next.js、Nuxt 3 或 Cloudflare Workers 的开发者尤为关键。

然而，该技能也存在明确的局限性。首先，它仅适合简单的显示/隐藏和排序动画，对于需要复杂手势交互（拖拽/滑动）、弹簧物理效果或滚动触发视差动画的场景，官方明确建议使用 motion-react 等更强大的库替代。其次，使用该技能需要严格遵守"父元素必须始终挂载"、"子元素使用唯一稳定 key"、"避免在 Flexbox 中使用 flex-grow"等约束，否则极易触发视觉异常。

目标用户群体主要为追求开发效率的前端工程师，特别是那些需要快速为管理后台、表单列表、通知中心添加丝滑动效，但又不想引入重型动画库的项目团队。对于教育类、企业级后台类产品尤为适合。

使用风险方面，除常规的 npm 依赖版本锁定外，需特别注意 React 19 环境下 StrictMode 的重复挂载问题（skill 已提供 useRef 标记解决方案），以及拖拽排序时必须手动移除 ref 以避免与 HTML5 Drag and Drop API 冲突。此外，虽然安全评级为 A 级，但来源属于 T3 社区级别，建议在使用前验证 scripts/init-auto-animate.sh 脚本内容，确保 npm 包仅从官方 registry 安装，避免供应链攻击。

核心用法

AutoAnimate 是 FormKit 出品的零配置动画库，仅需一行代码即可为列表、手风琴、Toast 等添加平滑过渡动画。支持 React、Vue、Solid、Svelte、Preact 五大框架，体积仅 3.28KB。

基础用法极其简单：

import { useAutoAnimate } from '@formkit/auto-animate/react'
const [parent] = useAutoAnimate()
return <ul ref={parent}>{items.map(...)}</ul>

显著优点

1. 真正零配置：无需定义 CSS 动画，自动计算 FLIP 动画
2. SSR 原生安全：自动尊重 prefers-reduced-motion，无障碍友好
3. 跨框架一致：同一套核心逻辑，各框架 API 统一
4. 极小体积：3.28KB，零运行时依赖
5. 活跃维护：v0.9.0 (2025-09)，React 19 兼容

潜在缺点与局限性

| 问题 | 说明 |

|------|------|

| 仅支持布局动画 | 无法做复杂手势/弹簧动画，需配合 Motion |

| Flex 容器限制 | `flex-grow` 会导致抖动，需用固定宽度 |

| 表格特殊处理 | 不能直接动画 `<tr>`，需包在 `<tbody>` |

| React 19 StrictMode | 需额外处理双重初始化（已提供方案） |

| 视口外动画失效 | Chrome 可能跳过离屏元素的 Animation API |

适合人群

• 需要快速添加列表/手风琴动画的 React/Vue 开发者
• 构建 SSR 应用（Next.js/Nuxt/Cloudflare Workers）需要避免 hydration 错误
• 追求极简 API、不想维护复杂动画代码的团队
• 重视无障碍，必须尊重用户动画偏好设置的项目

常规风险

1. SSR 导入错误：服务端渲染环境直接导入会崩溃，必须使用动态 import()
2. 条件渲染陷阱：父元素不能条件渲染 {show && <ul ref={parent}>}，子元素条件渲染才正确
3. Key 值错误：使用 index 作为 key 会导致动画错乱，必须用稳定唯一 ID
4. 拖拽冲突：enable(false) 在拖拽期间不可靠，需条件移除 ref

> ⚠️ 重要：该 Skill 为纯文档型，所有代码模板均为安全示例，无实际执行逻辑。推荐的 @formkit/auto-animate 库来自可信开源组织 FormKit（T2 来源）。