View Transition API 怎样只过渡局部元素

View Transition API 要只过渡局部元素，关键不是给所有页面套一层动画，而是先缩小过渡作用域。局部容器有自己的状态更新时，优先调用 Element.startViewTransition()；如果只能调用文档级的 document.startViewTransition()，就让 :root 不参与单独快照，再给目标元素设置唯一的 view-transition-name。

最稳妥的选择是“局部容器作为 transition root，局部 DOM 更新放进回调”。只有需要兼容文档级入口时，才使用命名快照方案。两种方案都要保留普通更新降级，不能把动画当成业务逻辑。

官方地址：https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using

先确定局部过渡的作用域

View Transition API 会把更新前后的画面做成旧视图和新视图快照。默认的文档级入口覆盖整个 transition root，因此只想让一个面板变化时，最先要解决的是“哪些 DOM 变化可以进入快照”。如果把页面根节点作为作用域，页面其他区域也可能参与默认的 root 过渡。

方案一：让局部容器成为 transition root

如果页面只是切换设置面板、预览卡片或列表中的一个区域，直接让容器调用 Element.startViewTransition() 更容易控制范围。回调里只修改这个容器的后代节点，页面外部不需要参与快照，也不会因为一个局部更新让整页都进入动画层。

const panel = document.querySelector("#settings-panel");

function showSettings(html) {
  const update = () => {
    // 只替换面板内部内容，避免把页面其他区域带入过渡范围
    panel.innerHTML = html;
  };

  if (!panel.startViewTransition) {
    // 不支持局部 API 时仍完成业务更新，动画只是增强效果
    update();
    return;
  }

  // 以 panel 作为 transition root，快照只覆盖它的 DOM 子树
  const transition = panel.startViewTransition(update);
  transition.finished.catch(() => {
    // 过渡被跳过时不回滚面板状态，可按需记录调试信息
  });
}

在元素作用域方案中，浏览器会为这个局部根建立自己的过渡伪元素树。你可以只调整局部 root 的旧、新视图动画；如果容器有 overflow: clip 或滚动裁剪，也更容易让过渡保持在容器边界内。

方案二：文档级入口只命名目标元素

有些项目的状态更新已经统一走 document.startViewTransition()，这时可以关闭默认的根快照，只让指定元素单独参与。下面的 CSS 把整个文档的默认快照设为 none，再为要变化的面板分配名称：

:root {
  /* 关闭文档根的默认快照，只保留明确命名的局部元素 */
  view-transition-name: none;
}

#settings-panel {
  /* 这个名称对应旧状态和新状态中的同一逻辑面板 */
  view-transition-name: settings-panel;
}

::view-transition-old(settings-panel),
::view-transition-new(settings-panel) {
  /* 只给局部面板设置淡入淡出，不影响页面其他内容 */
  animation-duration: 180ms;
  animation-timing-function: ease;
}

function replacePanel(html) {
  const update = () => {
    // 文档级入口下仍只改变目标面板的内容
    document.querySelector("#settings-panel").innerHTML = html;
  };

  if (!document.startViewTransition) {
    // 保留普通 DOM 更新，兼容不支持 View Transition API 的浏览器
    update();
    return;
  }

  // root 已被 CSS 排除，命名面板成为唯一的过渡快照
  document.startViewTransition(update);
}

门禁：名称、降级和动效偏好

局部化之后仍有三项必须守住的边界。

• 名称必须唯一：同一时刻不能让两个渲染元素使用同一个自定义名称，否则 ViewTransition.ready 可能拒绝，整次过渡会被跳过。列表场景可使用 match-element 自动分配同文档唯一名称，但它不适合跨文档复用。
• 更新必须在作用域内：元素级入口的回调不要顺手改动面板外的 DOM；若业务状态必须跨区域更新，就回到文档级入口并明确哪些元素命名参与。
• 尊重减少动态效果：系统偏好为 reduce 时，应关闭缩放和位移动画，保留清晰的内容更新。

@media (prefers-reduced-motion: reduce) {
  /* 减少动效时保留状态切换，但尽快结束局部动画 */
  ::view-transition-old(settings-panel),
  ::view-transition-new(settings-panel) {
    animation-duration: 1ms;
  }
}

我的判断

“只过渡局部元素”首先是作用域设计，其次才是动画曲线。一个独立面板优先使用元素级入口；已有统一文档级入口时，用 view-transition-name 精确挑出目标，并把 root 排除。无论哪条路径，都要让普通 DOM 更新可以独立完成，这样浏览器不支持或过渡被跳过时，页面仍然可用。

相关问题

为什么给元素设置了 view-transition-name，整页还是在淡入淡出？

命名元素只是从 root 快照中分离出来，并不会自动关闭 root 的默认动画。需要整页不动时，改用元素级入口，或显式把文档根设置为 view-transition-name: none。

局部元素可以同时设置多个相同名称吗？

不可以。名称是旧状态与新状态之间的对应标识，不是可复用的 CSS class。多个同名渲染元素会造成冲突；应使用不同名称，或用 match-element 让浏览器在同文档场景自动分配。