# View Transition

> document.startViewTransition() 为 DOM 状态变化添加动画。本参考说明生命周期 Promise、命名元素、失败处理和回退路径。

View Transition API 会在 DOM 改动前后捕获文档，再把两份捕获内容放进可由 CSS 动画控制的伪元素树。`document.startViewTransition(updateCallback)` 启动同文档过渡，并返回 `ViewTransition`；它的 Promise 分别对应内容更新、动画准备和动画结束。

## 浏览器支持

BCD 的 `api.Document.startViewTransition` 与 `api.ViewTransition` 记录：Chrome 111、Firefox 144 和 Safari 18 开始支持这组接口，相关移动版及 Chromium 衍生浏览器条目按相应引擎镜像；发布说明中，Firefox 144 对应单页应用支持，Safari 18 对应 Level 1 API。产品若仍覆盖旧版浏览器，还需同时查看[网页 API 兼容性数据](/zh/compatibility/api/)并做运行时检测。

## 语法

```js
const transition = document.startViewTransition(updateCallback)
const transition = document.startViewTransition({ update, types })

await transition.updateCallbackDone
await transition.ready
await transition.finished
transition.skipTransition()
```

Level 1 使用回调形式：浏览器捕获旧状态后异步执行回调，由回调里的 DOM 改动产生新状态。

Level 2 增加选项字典，`update` 成员接收更新回调，`types` 成员设置过渡类型。无论采用哪种形式，方法都会立即返回，不会等待回调或动画完成。

## 成员

返回对象把 DOM 更新、视觉过渡准备和动画结束拆成可单独等待的阶段。

| 成员 | 类型 | 含义 |
|---|---|---|
| `updateCallbackDone` | `Promise<undefined>` | 更新回调兑现时兑现；回调拒绝时以同一原因拒绝。 |
| `ready` | `Promise<undefined>` | 过渡伪元素已创建、动画即将开始时兑现；过渡无法开始时拒绝。 |
| `finished` | `Promise<undefined>` | 新状态已经可见且可交互时兑现；只有更新回调拒绝才会让它拒绝。 |
| `skipTransition()` | 方法 | 跳过或结束视觉过渡，但仍会执行更新回调。 |

浏览器依次捕获旧状态、暂停渲染、执行更新回调并捕获新状态，之后创建 `::view-transition` 伪元素树、运行 CSS 动画；默认效果是整页交叉淡化。某个元素若需要独立捕获，应在新旧状态中使用同一个唯一的 `view-transition-name`，再通过 `::view-transition-old(name)` 和 `::view-transition-new(name)` 分别控制离场与入场捕获内容。

等待哪个 Promise，取决于后续工作所需的阶段。只依赖 DOM 更新时等待 `updateCallbackDone`；要用 Web Animations API 控制生成的伪元素时等待 `ready`；工作必须在新状态可见且可交互后开始时，则等待 `finished`。调用 `skipTransition()` 不会改变更新回调的结果，`updateCallbackDone` 仍会反映该结果，页面也会进入更新后的状态。

## 异常

`startViewTransition()` 返回 `ViewTransition`，生命周期 Promise 异步报告失败。规范定义了以下路径。

| Promise | 失败条件 |
|---|---|
| `updateCallbackDone` | 更新回调抛错，或返回拒绝的 Promise。 |
| `ready` | 回调拒绝、文档处于隐藏状态、其他条件阻止捕获，或两个已渲染元素使用相同的 `view-transition-name`。 |
| `finished` | 更新回调拒绝。若只是跳过视觉过渡，页面仍会到达结束状态，此 Promise 会兑现。 |

文档的可见性状态为 `hidden` 时，启动的过渡会以 `InvalidStateError` 跳过。

若已有过渡处于活动状态，新过渡会让前一个以 `AbortError` 跳过，但两个异步回调仍可能运行。状态改动有先后依赖时，应由应用另行排队或取消，过渡对象本身不负责调度。

:::caution
Level 1 规范要求参与命名捕获的每个已渲染元素拥有唯一的 `view-transition-name`。捕获新状态或旧状态时，如果多个已渲染元素重名，`ready` 会以 `InvalidStateError` 拒绝；更新回调仍会运行，页面到达结束状态后 `finished` 仍会兑现（[捕获旧状态](https://www.w3.org/TR/css-view-transitions-1/#capture-the-old-state)，W3C）。
:::

## 示例

动画只包裹状态改动，不应成为完成改动的前提。下面两个例子在接口缺失时都会执行同一个 DOM 更新，因此按钮和选中内容在无过渡支持的浏览器中仍可使用。

### 切换面板并保留可用回退

这份完整文档在点击按钮后切换所选面板。回退分支直接调用 `selectPanel()`；支持接口的浏览器用 `startViewTransition()` 包住同一个调用。

```html
<!doctype html>
<html lang="zh-CN">
  <meta charset="utf-8" />
  <title>面板过渡</title>
  <button id="switch" type="button">显示详情</button>
  <main id="panel">摘要</main>
  <script>
    const button = document.querySelector("#switch");
    const panel = document.querySelector("#panel");

    function selectPanel() {
      panel.textContent = "详情";
      button.disabled = true;
    }

    button.addEventListener("click", () => {
      if (!("startViewTransition" in document)) {
        selectPanel();
        return;
      }
      document.startViewTransition(selectPanel);
    });
  </script>
</html>
```

两条分支的预期结果相同：正文显示“详情”，按钮变成禁用状态。支持接口的浏览器还会在改动外套用默认整页交叉淡化。若没有看到动画，先确认点击后是否得到上述结束状态，再检查动画样式。

### 从命名过渡失败中恢复

两个可见卡片若使用同一个 `view-transition-name`，`ready` 会拒绝。下面的代码用各卡片的 `data-id` 生成唯一名称；它还会处理更新回调拒绝，并在动画被跳过时保留已经成功的 DOM 改动。

```js
const status = document.querySelector("#status");
const cards = [...document.querySelectorAll(".card")];

function assignUniqueNames() {
  for (const card of cards) {
    card.style.viewTransitionName = `card-${card.dataset.id}`;
  }
}

async function reorderCards() {
  assignUniqueNames();
  if (!("startViewTransition" in document)) {
    cards[0].parentNode.append(...[...cards].reverse());
    status.textContent = "已重排，未播放动画";
    return;
  }

  const transition = document.startViewTransition(() => {
    cards[0].parentNode.append(...[...cards].reverse());
  });

  transition.updateCallbackDone.catch((error) => {
    status.textContent = `更新失败：${error.name}`;
  });
  transition.ready.catch((error) => {
    status.textContent = `动画已跳过：${error.name}`;
  });
  await transition.finished.catch(() => {});
}
```

给每个 `.card` 设置不同的 `data-id`。若 `ready` 报告 `InvalidStateError`，检查计算后的 `view-transition-name` 是否重复。若 `updateCallbackDone` 拒绝，应先修复更新回调，因为 `finished` 也会按同一回调失败；只有 `ready` 拒绝时，DOM 更新仍可能已经成功。

## 另请参阅

- [Navigation API](/zh/reference/capabilities/navigation-api/)，拦截和管理同文档导航
- [用户激活](/zh/reference/capabilities/user-activation/)，了解与用户手势绑定的 API 调用
- [CSS View Transitions Module Level 1](https://www.w3.org/TR/css-view-transitions-1/)（W3C）
- [单页应用的同文档视图过渡](https://developer.chrome.com/docs/web-platform/view-transitions/same-document)（Chrome for Developers）
- [Safari 18.0 中的 WebKit 功能](https://webkit.org/blog/15865/webkit-features-in-safari-18-0/)（WebKit）