用途:指导在 React 应用中用浏览器原生 document.startViewTransition 实现界面状态间的动画。用 <ViewTransition> 声明动画对象,用 startTransition、useDeferredValue 或 Suspense 触发,用 CSS 类控制动画方式;不支持的浏览器会优雅跳过动画。
主要能力:<ViewTransition> 组件自动分配 view-transition-name 并调用 startViewTransition,无需手动调用。触发类型包括 enter、exit、update、share。可用 addTransitionType 为过渡打标签,并按类型映射不同 CSS 类,实现前进/后退等方向性动画。支持共享元素 morph、列表重排、Suspense 揭示、布局位移等模式。
使用方式:从 react 导入 ViewTransition;只有 startTransition、useDeferredValue 或 Suspense 会激活过渡,普通 setState 不会。组件需出现在任何 DOM 节点之前才能激活 enter/exit。用 default="none" 关闭默认交叉淡入,按需显式开启。共享元素需两个视图使用相同 name,且同一时刻只能挂载一个同名 VT。
适用场景:层级导航(列表到详情)、有序序列(上一张/下一张)、Suspense 内容揭示、列表身份与重排、状态进入退出。横向或无顺序导航不宜用方向性滑动。
限制:Next.js 16.3 起 App Router 无需配置即可用,不要安装 react@canary,也不要加旧的 experimental.viewTransition 标志;非 Next.js 需 React 19.3+ 稳定版。TypeScript 需 @types/react 19.3+。浏览器需 Chromium 125+、Firefox 144+、Safari 18.2+,Safari 部分动画表现可能不同。router.back() 与浏览器前进后退不携带过渡类型,类型化动画会落到默认值;React 19.3 中旧式 popstate 遍历可能跳过所有视图过渡。嵌套 VT 在父级整体挂载/卸载时不会触发自身 enter/exit。需始终加入减少动态效果的 CSS。具体 CSS 配方、实现步骤与排错见其参考文件。