React ViewTransition：配合 Transition 做进出场与共享元素动画

React 官方文档把 <ViewTransition> 定义为：用 Transition、Suspense 给组件树做动画的边界组件。包一层后，React 会在需要参与动画时给最近的 DOM 节点挂上 view-transition-name，并自己调用 startViewTransition。文档明确说不要再手写 startViewTransition；页面上若有别的 View Transition 在跑，React 会打断它，所以建议统一交给 React 协调。[1]

激活条件很窄。普通 setState 默认立刻更新，不会触发；只有包在 Transition、落在 Suspense，或走 useDeferredValue 的更新才会。动画类型分四种：本次 Transition 里首次插入走 enter，删除走 exit，边界内 DOM 变更或紧邻兄弟导致尺寸位置变化走 update；同名边界在同一次 Transition 里一边卸载一边挂载，则走 share（共享元素）。默认效果是浏览器自带的交叉淡入淡出。[1]

共享元素才需要自己设 name；其余场景让 React 自动起名，免得串动画。name 在整个应用同一时刻只能挂一个实例，列表项要带 id 做命名空间。进出场还要求 ViewTransition 出现在任何 DOM 节点之前，外面先包一层 <div> 常常会让 enter/exit 失效。样式可用 enter / exit / update / share / default 传入 Class，再写 ::view-transition-*；也可用 onEnter 等事件接 Web Animations API。文档提醒：React 不会自动处理 prefers-reduced-motion，需要自己用媒体查询减弱或关闭。目前主要支持 DOM。[1]

落地时可以先从「列表增删」或「全屏切换缩略图」这类场景试：用 startTransition 包住状态切换，再在最外层放 ViewTransition。共享元素只在确实需要跨树连续感时再起名。若动画完全不动，优先检查是不是更新没走 Transition，以及边界外面是不是多包了一层 DOM。文档示例依赖较新的 React，接入前先核对本项目 React 主版本是否已包含该导出。

说明：据 react.dev 参考页整理，细节以当前文档与所用 React 版本为准。

来源

[1] React 文档：ViewTransition，查询日 2026-10-29。

#React #ViewTransition #动画 #Suspense #前端