view-transitions

用途

View Transitions 用于为 Web 应用添加原生、平滑的视图切换动画，主要覆盖以下场景：

SPA 中的页面导航过渡
MPA 跨文档（cross-document）过渡
共享元素动画（图片画廊、卡片）
模态框到页面的过渡
列表项到详情页的动画
带平滑过渡的标签页切换

主要能力

核心能力围绕浏览器的 View Transitions API 展开，包括：

React Router 7.x 集成：在 Link、NavLink、Form 上启用 viewTransition 属性，实现最简单的过渡接入。
useViewTransitionState 钩子：在过渡进行中动态设置 viewTransitionName，实现共享元素匹配。
手动 startViewTransition（SPA）：通过 document.startViewTransition 包裹导航或 React 状态更新；React 状态更新需配合 ReactDOM.flushSync 才能正确捕获。
跨文档过渡（MPA）：在源文档与目标文档中通过 @view-transition { navigation: auto; } 启用，并用 ::view-transition-old/new(root) 自定义动画。
共享元素过渡：通过相同的 view-transition-name 在列表页与详情页之间实现元素形变（morph）动画。
导航事件：监听 pageswap / pagereveal 事件，根据前进或后退方向动态添加过渡类型。
过渡类型（Transition Types）：通过 types 参数与 CSS 选择器 html:active-view-transition-type(...) 针对不同导航类型应用不同动画。
CSS 伪元素定制：可操作 ::view-transition-group、::view-transition-image-pair、::view-transition-old、::view-transition-new 等伪元素，控制动画时长、缓动与混合模式。
渐进增强与特性检测：通过检测 document.startViewTransition 是否存在、CSS @supports 判断，在不支持的浏览器中回退为无动画导航。
可访问性：通过 prefers-reduced-motion 媒体查询或 useMediaQuery 钩子完全跳过动画，尊重用户的减少动态偏好。

使用方式

使用方式按场景分为几类：

React Router 7.x：直接为 Link/NavLink/Form 添加 viewTransition 属性。
SPA 手动控制：调用 document.startViewTransition(() => navigate(to))，状态更新时使用 ReactDOM.flushSync 包裹。
共享元素：源元素与目标元素设置相同的 viewTransitionName。
MPA：在 CSS 中声明 @view-transition { navigation: auto; }，配合 pageswap / pagereveal 事件定制。
过渡类型：在 startViewTransition 的 types 参数中传入类型名，CSS 侧通过 html:active-view-transition-type 针对性定义动画。
降级：用 typeof document.startViewTransition 或 @supports (view-transition-name: none) 做特性检测。

关键决策参考：SPA 推荐手动触发、MPA 推荐自动；动画时长建议 200-300ms；静态共享元素用 CSS 名称、动态列表用 JS 动态命名；不支持时使用 CSS 回退动画；减少动态偏好时直接跳过。

适用场景

适合需要提升导航体验的 React Web 应用，尤其是图片画廊、商品卡片列表、列表到详情、标签切换等强调元素连贯性的界面；同时适用于需要统一处理 SPA 与 MPA 过渡的站点。

限制与注意事项

浏览器支持：同文档过渡 Chrome 111+、Edge 111+、Safari 18+ 支持；跨文档过渡 Chrome/Edge 126+、Safari 18.2+ 支持；Firefox 暂不支持（开发中）。
反模式（禁止）：
- 重复的 view-transition-name（必须唯一，否则过渡失效）。
- 在隐藏元素（如 display: none）上设置 viewTransitionName。
- React 状态更新时缺少 flushSync，导致捕获不正确。
- 在滚动中触发过渡（性能问题）。
- 过长的动画阻塞导航交互（如 2s）。
- 忘记渐进增强，在不支持的浏览器中直接使用 viewTransition 会失效。

参考文件

references/react-router-integration.md：React Router 7.x 模式
references/mpa-transitions.md：跨文档过渡
scripts/view-transition-wrapper.tsx：过渡包装组件

以上信息均来自提供的资料，未提供的收费、价格等信息暂未提供。

技能介绍

用途