文档:startViewTransition() 方法

可用性有限

此特性不是基线特性,因为它在一些最广泛使用的浏览器中不起作用。

Document 接口的 startViewTransition() 方法会启动一个新的同文档 (SPA) 视图过渡,并返回一个 ViewTransition 对象来表示它。

调用 startViewTransition() 时,会遵循 视图过渡过程 中所述的一系列步骤。

语法

js
startViewTransition()
startViewTransition(updateCallback)
startViewTransition(options)

参数

updateCallback 可选

一个可选的回调函数,通常在 SPA 视图过渡过程中调用以更新 DOM,它会返回一个 Promise。在 API 捕获当前页面快照后调用此回调。当回调返回的 Promise fulfilled 时,视图过渡将在下一帧开始。如果回调返回的 Promise rejected,则过渡将被放弃。

options 可选

一个包含用于配置视图过渡的选项的对象。它可以包含以下属性:

update 可选

上面描述的相同的 updateCallback 函数。默认为 null

types 可选

一个字符串数组。这些字符串充当过渡的类名或标识符,允许你根据发生的过渡类型选择性地应用 CSS 样式或运行不同的 JavaScript 逻辑。默认为空序列。

返回值

一个 ViewTransition 对象实例。

示例

使用同文档视图过渡

在此同文档视图过渡中,我们检查浏览器是否支持视图过渡。如果不支持,我们会使用一种回退方法设置背景颜色,该方法会立即应用。否则,我们可以安全地调用 document.startViewTransition() 并使用我们在 CSS 中定义的动画规则。

html
<main>
  <section></section>
  <button id="change-color">Change color</button>
</main>

我们使用 ::view-transition-group 伪元素将 animation-duration 设置为 2 秒。

css
html {
  --bg: indigo;
}
main {
  display: flex;
  flex-direction: column;
  gap: 5px;
}
section {
  background-color: var(--bg);
  height: 60px;
  border-radius: 5px;
}
::view-transition-group(root) {
  animation-duration: 2s;
}
js
const colors = ["darkred", "darkslateblue", "darkgreen"];
const colBlock = document.querySelector("section");
let count = 0;
const updateColour = () => {
  colBlock.style = `--bg: ${colors[count]}`;
  count = count !== colors.length - 1 ? ++count : 0;
};
const changeColor = () => {
  // Fallback for browsers that don't support View Transitions:
  if (!document.startViewTransition) {
    updateColour();
    return;
  }

  // With View Transitions:
  const transition = document.startViewTransition(() => {
    updateColour();
  });
};
const changeColorButton = document.querySelector("#change-color");
changeColorButton.addEventListener("click", changeColor);
changeColorButton.addEventListener("keypress", changeColor);

如果支持视图过渡,点击按钮将在 2 秒内将颜色从一种过渡到另一种。否则,背景颜色将使用回退方法设置,没有任何动画。

规范

规范
CSS 视图过渡模块第 1 级
# dom-document-startviewtransition
CSS 视图过渡模块级别 2
# dom-document-startviewtransition

浏览器兼容性

另见