auto-animate

用途

AutoAnimate 是一个零配置动画库，包名为 @formkit/auto-animate，体积约 3.28kb，支持 React、Vue、Solid、Svelte、Preact 等框架。它通过给父元素绑定 ref，自动为子元素的添加、删除和移动添加过渡动画，无需手写动画逻辑。本技能是一份错误预防指南，帮助开发者规避该库的 15 个已知问题。

主要能力

零配置：只需将 ref 绑定到父元素即可启用动画。
多框架支持：React、Vue、Solid、Svelte、Preact。
自动尊重 prefers-reduced-motion（不应关闭此行为）。
提供 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;
}

安装依赖：

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

15 个已知问题与预防

SSR/Next.js 导入错误：AutoAnimate 使用服务端不可用的 DOM API，应使用动态导入。
条件渲染父元素：ref 无法绑定到不存在的元素，应保持父元素始终渲染，仅条件渲染子元素。
缺少唯一 key：应使用稳定唯一 key（如 key={item.id}），不要用索引。
Flexbox 宽度与抖动：flex-grow 会导致时序问题，应使用显式固定宽度。
表格行显示问题：display: table-row 与动画冲突，应作用于 tbody 或改用 div 布局。
Jest 测试错误：Jest 无法正确解析 ESM 导出，需配置 moduleNameMapper。
esbuild 兼容性：ESM/CommonJS 条件不匹配，需正确配置 esbuild。
CSS position 副作用：父元素会被自动加上 position: relative，需在 CSS 中考虑或显式设置。
Vue/Nuxt 注册错误：插件未正确注册，需在配置中正确设置；Nuxt 3 需 v0.8.2+。
Angular ESM 问题：CommonJS 构建环境导致失败，需为 Angular Package Format 配置 ng-packagr。
React 19 StrictMode 双重调用：StrictMode 会调用两次 useEffect，需用 ref 跟踪初始化。
视口外动画失效：Chrome 可能不为屏幕外元素运行动画 API，应确保父元素可见后再应用。
删除元素遮挡内容：退出动画保持 z-index 覆盖内容，需显式处理 z-index。
拖拽时无法禁用：enable(false) 在拖拽中不可靠，应在拖拽时条件性移除 ref。
父级 transform 位置错误：元素记住 transform 前的位置，应延迟到 transform 完成后再启用。

关键规则

应做：使用唯一稳定 key；保持父元素在 DOM 中；SSR 环境仅客户端导入；保留对减少动效偏好的尊重；在禁用动效下测试；使用显式宽度；表格作用于 tbody。

不应做：条件渲染父元素；用索引作 key；忽略 SSR；强制动画（disrespectUserMotionPreference: true 会破坏无障碍）；直接动画表格；跳过唯一 key；使用复杂动画（复杂场景应改用 Motion）。

适用场景

列表增删与排序、手风琴、Toast 通知、表单等需要轻量过渡动画的前端界面。

限制

仅适合简单过渡动画，复杂动画应使用 Motion。存在上述 15 个已知问题需按指南规避。社区技巧（如测试冻结、内存泄漏预防）来自社区讨论，需自行对照版本验证。

版本信息

最新版本：@formkit/auto-animate@0.9.0（2025 年 9 月 5 日）。v0.8.2（2024 年 4 月 10 日）修复了 Nuxt 3 ESM 导入与 ResizeObserver 守卫。框架兼容：React 18+、Vue 3+、Solid、Svelte、Preact。Nuxt 3 用户需 v0.8.2+。

官方资源

官网：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