跳转到内容

能力中的 API

View Transition

发布于

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 兼容性数据并做运行时检测。

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 跳过,但两个异步回调仍可能运行。状态改动有先后依赖时,应由应用另行排队或取消,过渡对象本身不负责调度。

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

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

<!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 改动。

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 更新仍可能已经成功。

规范

规范状态
CSS View Transitions Module Level 1: APIW3C
CSS View Transitions Module Level 2其他