能力中的 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.updateCallbackDoneawait transition.readyawait transition.finishedtransition.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 更新仍可能已经成功。
另请参阅
链接到“另请参阅”一节- Navigation API,拦截和管理同文档导航
- 用户激活,了解与用户手势绑定的 API 调用
- CSS View Transitions Module Level 1(W3C)
- 单页应用的同文档视图过渡(Chrome for Developers)
- Safari 18.0 中的 WebKit 功能(WebKit)
规范
| 规范 | 状态 |
|---|---|
| CSS View Transitions Module Level 1: API | W3C |
| CSS View Transitions Module Level 2 | 其他 |