浏览器 View Transition 如何只动画列表中的一个元素

列表页只改了一条记录，却把整页一起淡入淡出，通常不是 CSS 动画写错，而是 View Transition 默认把文档根节点当成了过渡范围。要只动画一个列表项，关键是先让根节点退出独立快照，再给目标元素设置唯一的 view-transition-name，最后把 DOM 更新放进 document.startViewTransition() 的回调里。

把“页面更新”与“动画对象”分开：更新函数仍然只改目标列表项，过渡名称则只挂在这个元素上。浏览器不支持 API 时，直接执行同一个更新函数即可。

为什么给一项加动画会牵动整页

document.startViewTransition() 是文档范围的同文档过渡入口。调用后，浏览器会为旧状态和新状态创建快照；默认的根快照覆盖页面的大部分内容，所以即使回调只改了一行文字，用户也可能看到整块页面参与淡入淡出。

view-transition-name 的作用是把某个元素从默认根过渡中分离出来，单独生成自己的过渡组。这里的“只动画一个元素”不是让其他节点消失，而是让它们继续作为普通 DOM 显示，不再拥有独立的动画对象。

先让 View Transition 只看目标列表项

先把根元素的参与方式改成 none，再为目标项准备一个不会与其他渲染元素重复的名称。下面的样式保留默认的尺寸过渡，只把目标项的旧、新快照设为轻微缩放和淡入淡出；不需要复杂效果时，也可以删掉动画定义，使用浏览器默认过渡。

/* 关闭文档根的独立快照，只保留显式命名的元素 */
:root {
  view-transition-name: none;
}

/* selected-item 只允许同时出现在一个渲染元素上 */
::view-transition-group(selected-item) {
  animation-duration: 280ms;
}

/* 让目标列表项的离场和入场保持轻量 */
::view-transition-old(selected-item),
::view-transition-new(selected-item) {
  animation-duration: 280ms;
  animation-timing-function: ease-out;
}

::view-transition-old(selected-item) {
  animation-name: item-out;
}

::view-transition-new(selected-item) {
  animation-name: item-in;
}

@keyframes item-out {
  to { opacity: 0; transform: translateY(-4px) scale(.98); }
}

@keyframes item-in {
  from { opacity: 0; transform: translateY(4px) scale(.98); }
}

根节点设为 none 后，显式命名的目标项仍然可以创建自己的快照。不要把同一个自定义名称静态写在多个列表项上；列表有多行时，应该在更新前只给当前项临时命名。

把一次列表更新放进 startViewTransition

下面示例点击按钮后只修改一个列表项的标题。注意顺序：先找到稳定存在的目标节点，再在调用 API 前挂上名称；回调只负责 DOM 更新。动画结束后把名称恢复成 none，避免下一次操作遇到残留命名。

    整理接口文档
    标记完成
  
  

    补充错误码说明
  

const list = document.querySelector("#todo-list");
let transitionRunning = false;

function updateItem(itemId, nextTitle) {
  const item = list.querySelector(`[data-id="${itemId}"]`);
  if (!item) return;

  // 过渡未结束前不再给第二个元素命名，避免快照重叠
  if (transitionRunning) return;

  const update = () => {
    // 只改目标节点，避免重建整个列表导致名称失去对应关系
    item.querySelector(".title").textContent = nextTitle;
  };

  // 不支持 View Transition 时仍完成同一个 DOM 更新
  if (typeof document.startViewTransition !== "function") {
    update();
    return;
  }

  // 一个自定义名称只绑定当前这个渲染元素
  item.style.viewTransitionName = "selected-item";
  transitionRunning = true;
  const transition = document.startViewTransition(update);

  transition.finished.finally(() => {
    // 清理名称，防止后续操作出现重复命名
    item.style.viewTransitionName = "none";
    transitionRunning = false;
  });
}

list.addEventListener("click", (event) => {
  const button = event.target.closest("[data-edit]");
  if (button) updateItem(button.dataset.edit, "已完成：整理接口文档");
});

示例中的 transition.finished 只用于清理状态，不决定 DOM 是否更新。即使浏览器跳过动画，功能本身也应由 update 完成。真实项目里如果列表项会被删除或替换，要在回调中确认目标节点仍然存在，并避免给已经脱离文档的节点设置名称。

列表频繁更新时如何避免名称冲突

自定义名称是当前渲染树中的身份标识，不是普通 CSS class。如果两个可渲染元素同时拥有相同的 view-transition-name，过渡的 ready Promise 可能拒绝，浏览器会跳过这次动画。列表场景最稳妥的做法是“一次一个目标项”，或者为每个正在参与的元素生成真正唯一的名称。

为旧浏览器保留直接更新降级

View Transition 是增强效果，不应成为列表编辑的前置条件。用 typeof document.startViewTransition 做能力检测，把实际修改抽成独立的 update 函数，就能让不支持的浏览器直接看到新文本。也不要用“动画结束”作为保存成功的条件，数据提交、错误提示和可访问状态应与动画生命周期分开。

如果目标是拖拽排序、连续输入或高频实时数据，先评估更新频率和用户是否需要过渡；对每次击键都建立快照通常没有必要。对一次明确的编辑、筛选结果替换或单个状态切换，元素级命名更容易控制。

常见问题

可以直接给所有列表项写同一个 view-transition-name 吗？

不建议。多个渲染元素共享同一自定义名称会产生身份冲突；如果确实要同时动画多个项，请为每个元素生成唯一名称。

只设置 view-transition-name，不调用 startViewTransition 可以吗？

不行。名称只说明哪些元素可以进入快照，仍需要由文档或元素级的 View Transition 入口触发一次状态更新。

为什么动画偶尔没有出现？

先检查 API 能力、页面是否处于可见状态，以及当前名称是否重复；再确认 DOM 更新确实发生在过渡回调中。动画缺失不等于文本更新失败。

参考资料：https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API、https://developer.mozilla.org/en-US/docs/Web/API/Document/startViewTransition