用途:为 React 与 Next.js 应用添加视图过渡、共享元素动画、路由过渡与过渡类型,并保证在减少动效设置下安全。核心是使用浏览器原生 document.startViewTransition,由 React 的 <ViewTransition> 组件自动分配 view-transition-name 并调用底层 API,不要自行调用 startViewTransition。
主要能力:<ViewTransition> 支持 enter、exit、update、share 四类触发;只有 startTransition、useDeferredValue 或 Suspense 会激活过渡,普通 setState 不会。属性值可为 "auto"、"none"、自定义类名,或按过渡类型映射的对象。可用 addTransitionType 为过渡打标签,让不同 <ViewTransition> 按上下文选择动画。共享元素通过两个 VT 使用相同 name 实现形变。
使用方式:Next.js App Router 已内置 React canary,无需安装 react@canary;非 Next.js 需安装 react@canary react-dom@canary。浏览器支持 Chromium 111+、Firefox 144+、Safari 18.2+,不支持时优雅降级。建议先做审计,再按 references/implementation.md 步骤实施,CSS 动画直接复制 references/css-recipes.md,不要自写。
适用场景:层级导航(列表到详情)用类型键控的方向滑动;横向导航用淡入淡出或 default="none";Suspense 揭示用 enter/exit 字符串;后台刷新用 default="none"。列表重排、共享元素与列表身份需用嵌套 VT 分层处理。
限制:router.back() 与浏览器前进后退不触发过渡,应改用 router.push()。同一 name 的 VT 同时只能挂载一个,需用唯一名称。父 VT 退出时嵌套 VT 不触发自身 enter/exit。类型在后续 Suspense 揭示中不可用。务必全局加入减少动效 CSS,并大量使用 default="none" 避免意外动画。具体实现细节与完整代码示例见资料中的参考文件。