HTML View Transition API 是一个强大但极易误用的现代浏览器动画机制，它并非简单的“HTML字符串转动画”工具，而是严格依赖已挂载、可匹配的DOM元素，通过成对且稳定的`view-transition-name`属性触发精准快照过渡；其核心限制在于：必须在`startViewTransition`回调中执行**同步DOM更新**，严禁异步操作干扰快照时机；过渡元素需全程保持可见与挂载状态，避免`display: none`、`opacity: 0`等导致快照失效；同时它不支持传统多页应用（MPA）的跨页面导航，仅适用于单页应用（SPA）模式下的动态DOM替换。若动画静默失败，大概率是name不匹配、DOM未就绪或结构错位所致——建议从最简双元素配对开始验证，逐步排查，才能真正释放其丝滑流畅的视觉过渡潜力。

View Transitions API 不是“把 HTML 字符串转成过渡效果”的工具，它只对已挂载、可匹配的 DOM 元素生效。直接 document.body.innerHTML = htmlString 后调用 startViewTransition，大概率没动画——因为旧元素已被销毁，快照捕获失败。

startViewTransition 回调里只能写同步 DOM 更新

浏览器在回调执行前拍一次快照，执行完再拍一次，中间必须是**立即可见的 DOM 变更**。任何 await、setTimeout、fetch().then() 套在外面都会导致快照错位。

• ❌ 错误：在回调外等数据，再更新 DOM
• const res = await fetch('/post');
• document.startViewTransition(() => { article.innerHTML = res.text(); }); // res.text() 是 Promise，不是字符串
• ✅ 正确：先取数据，再进回调同步写入
• fetch('/post').then(r => r.text()).then(html => {
•   document.startViewTransition(() => { article.innerHTML = html; });
• });
• ⚠️ 注意：如果 article 是空容器或刚创建，确保它已在 document 中（不能是 document.createElement('div') 后还没 append）

view-transition-name 必须成对、稳定、唯一

过渡是否触发，90% 取决于这个属性是否配对成功。它不是 class，不是 id，是独立的 CSS 属性，靠值精确匹配。

• 旧元素和新元素都得有 view-transition-name: title，且值完全一致（大小写敏感）
• 值不能是空、none 或动态生成（比如 view-transition-name: item-${id} 但前后 id 不一致）
• 不要给非目标元素乱加该属性，否则它们也会被卷入过渡，干扰动画层叠
• 推荐写法：

  旧标题

  → 新 DOM 中同样位置也带 style="view-transition-name: title"

过渡卡顿或闪烁，大概率是样式触发了不可见快照

View Transition 依赖合成层快照，以下 CSS 会让浏览器无法捕获旧元素视觉状态：

• transform: scale(0)、opacity: 0、visibility: hidden 等隐藏类若在快照前已生效，旧元素就“不可见”，动画只剩新元素淡入
• 解决办法：过渡开始前，确保待动画元素处于可见、可绘制状态（哪怕只是 opacity: 0.999）
• 不要在 startViewTransition 调用前给元素加 display: none 或移除它；如需 loading 状态，用占位结构或透明遮罩，别动目标元素本身
• 检查 DevTools 的 Layers 面板，确认过渡元素是否进入了独立合成层（will-change: transform 可辅助，但非必需）

多页应用（MPA）中无法直接使用 View Transition

View Transition 只响应同一文档内 DOM 的变更，不接管跨页面导航。用户点链接跳转到新 HTML 文件时，旧页面已卸载，API 无从介入。

• ✅ 可行方案：改用 SPA 模式，用 history.pushState() + 手动 DOM 替换 + startViewTransition
• ❌ 不可行方案：在 window.onload 或 DOMContentLoaded 里调用 startViewTransition，此时没有“旧视图”可捕获
• 替代思路（MPA 场景）：监听 pageswap 事件做轻量级 CSS 过渡，或用 document.visibilityState 配合自定义 fade 动画

最易忽略的一点：过渡动画是否生效，和 JS 是否报错无关。startViewTransition 静默失败很常见——元素没匹配上、name 写错、DOM 未挂载、甚至只是用了 innerHTML 却没清空旧子节点导致结构错位。建议先用最简 case 验证：两个带相同 view-transition-name 的