`。 ### 把共享元素与列表标识组合在一起共享元素与列表标识是正交的两个关注点 —— 不要混淆。在列表项包含共享元素（例如，变形到详情视图的图片）的场景下，使用两层嵌套的 `` 边界： ```jsx {items.map(item => ( {/* list identity */} {/* shared element */}

{item.name}

))} ``` 外层 VT 处理列表重排 / 进入动画。内层 VT 处理跨路由共享元素变形。缺少任何一层都会让对应的动画静默失效。 ### 用 `key` 强制重新进入 ```jsx ``` **注意：** 如果包裹的是 ``，修改 `key` 会重新挂载该边界并重新请求数据。 ### Suspense Fallback → 内容简单交叉淡入淡出： ```jsx }> ``` 方向性揭示： ```jsx }> ``` 更多模式见 `references/patterns.md`。 --- ## 多个 VT 的交互方式每个匹配触发器的 VT 会在同一次 `document.startViewTransition` 中同时触发。位于**不同**过渡中的 VT（导航 vs 后续的 Suspense 解析）之间不会相互竞争。 ### 自由使用 `default="none"` 如果不加 `default="none"`，每一个 VT 在**每一次**过渡中都会触发浏览器交叉淡入淡出 —— Suspense 解析、`useDeferredValue` 更新、后台重新校验。始终使用 `default="none"`，并仅显式启用所需的触发器。 ### 两种模式共存 **模式 A —— 方向性滑动：** 在每个页面上使用按类型键控的 VT，在导航期间触发。 **模式 B —— Suspense 揭示：** 使用简单的字符串属性，在数据加载时触发（不带类型）。它们之所以能共存，是因为触发时机不同。两端都加 `default="none"` 可防止相互干扰。始终让 `enter` 与 `exit` 成对出现。把方向性 VT 放在页面组件中，而不是布局中。 ### 嵌套 VT 的限制当父级 VT 退出时，其内部的嵌套 VT **不会**触发各自的 enter/exit —— 只有最外层的 VT 会播放动画。页面导航期间按项错开的动画目前无法实现。可参考 [react#36135](https://github.com/facebook/react/pull/36135) 了解实验性的 opt-in 修复方案。 --- ## Next.js 集成关于 Next.js 的设置（`experimental.viewTransition` 标志、`next/link` 上的 `transitionTypes` 属性、App Router 模式、Server Components），请参考 `references/nextjs.md`。 --- ## 无障碍务必把 `references/css-recipes.md` 中支持 reduced motion 的 CSS 加入你的全局样式表。 --- ## 参考文件 - **`references/implementation.md`** —— 分步的实施工作流。 - **`references/patterns.md`** —— 模式、动画时序、Events API、故障排查。 - **`references/css-recipes.md`** —— 可直接使用的 CSS 动画配方。 - **`references/nextjs.md`** —— Next.js App Router 模式与 Server Component 细节。 ## 完整编译文档包含所有参考文件展开后的完整指南：`AGENTS.md` ## 局限性 - 仅当任务明确匹配上述范围时使用此技能。 - 不要把输出当作针对具体环境的验证、测试或专家评审的替代品。 - 当所需的输入、权限、安全边界或成功标准缺失时，停下来向用户确认。