适用于单页应用的同文档视图转换

Jake Archibald

Bramus

发布时间：2021 年 8 月 17 日；最后更新时间：2024 年 9 月 25 日

当视图转换在单个文档上运行时，称为同一文档视图转换。使用 JavaScript 更新 DOM 的单页应用 (SPA) 中通常就属于这种情况。从 Chrome 111 开始，Chrome 支持同一文档视图转换。

如需触发同文档视图转换，请调用 document.startViewTransition：

function handleClick(e) {
  // Fallback for browsers that don't support this API:
  if (!document.startViewTransition) {
    updateTheDOMSomehow();
    return;
  }

  // With a View Transition:
  document.startViewTransition(() => updateTheDOMSomehow());
}

被调用时，浏览器会自动截取为其声明了 view-transition-name CSS 属性的所有元素的快照。

然后，它会执行传入的回调以更新 DOM，之后会拍摄新状态的快照。

然后，这些快照会排列在伪元素树中，并使用强大的 CSS 动画功能进行动画处理。旧状态和新状态的两对快照会从其旧位置和大小平滑过渡到新位置，同时其内容会交叉淡出淡入。如果需要，您可以使用 CSS 自定义动画。

---

默认转场效果：交叉淡出

默认的视图过渡是淡入淡出，因此为 API 提供了很好的介绍：

function spaNavigate(data) {
  // Fallback for browsers that don't support this API:
  if (!document.startViewTransition) {
    updateTheDOMSomehow(data);
    return;
  }

  // With a transition:
  document.startViewTransition(() => updateTheDOMSomehow(data));
}

其中 updateTheDOMSomehow 会将 DOM 更改为新状态。您可以随意选择合适的方式。例如，您可以添加或移除元素、更改类名称或更改样式。

这样一来，页面就会交叉淡出淡入：

默认的淡出效果。最小演示版。来源。

好的，交叉淡化效果不是很出色。幸运的是，您可以自定义转场效果，但首先，您需要了解这种基本交叉淡化效果的运作方式。

注意 ：本文档中的演示链接在视觉效果方面不够直观，但代码库非常小。我们的目标是让所有代码更易于阅读和理解，而无需了解任何特定的 SPA 框架。

---

这些转换的运作方式

我们来更新一下上一个代码示例。

document.startViewTransition(() => updateTheDOMSomehow(data));

调用 .startViewTransition() 时，该 API 会捕获页面的当前状态。这包括拍摄快照。

完成后，系统会调用传递给 .startViewTransition() 的回调。DOM 就是在该位置发生变化的。然后，API 会捕获页面的新状态。

捕获新状态后，该 API 会构建一个伪元素树，如下所示：

::view-transition
└─ ::view-transition-group(root)
   └─ ::view-transition-image-pair(root)
      ├─ ::view-transition-old(root)
      └─ ::view-transition-new(root)

::view-transition 位于叠加层中，叠加在页面上的所有其他内容之上。如果您想为转场效果设置背景颜色，这会非常有用。

::view-transition-old(root) 是旧视图的屏幕截图，::view-transition-new(root) 是新视图的实时表示法。这两者都会渲染为 CSS“替换内容”（例如 <img>）。

旧视图会以动画形式从 opacity: 1 到 opacity: 0，而新视图会从 opacity: 0 以动画形式呈现到 opacity: 1，从而创建淡入淡出。

所有动画均使用 CSS 动画执行，因此可以使用 CSS 对其进行自定义。

注意：旧版和新版视图也具有 mix-blend-mode: plus-lighter，::view-transition-image-pair 具有 isolation: isolate。这是创建正确的淡出淡入所必需的。如果您想了解原因，请参阅关于该主题的字数过多。

自定义转场效果

所有视图过渡伪元素都可以使用 CSS 进行定位，而且由于动画是使用 CSS 定义的，因此您可以使用现有的 CSS 动画属性对其进行修改。例如：

::view-transition-old(root),
::view-transition-new(root) {
  animation-duration: 5s;
}

完成这项更改后，淡变效果现在非常慢：

<ph type="x-smartling-placeholder">

</ph>

长的淡入淡出。最小演示版。来源。

好的，这仍然不够理想。而以下代码会实现 Material Design 的共享轴转场：

@keyframes fade-in {
  from { opacity: 0; }
}

@keyframes fade-out {
  to { opacity: 0; }
}

@keyframes slide-from-right {
  from { transform: translateX(30px); }
}

@keyframes slide-to-left {
  to { transform: translateX(-30px); }
}

::view-transition-old(root) {
  animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}

::view-transition-new(root) {
  animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}

结果如下：

<ph type="x-smartling-placeholder">

</ph>

共享轴转换。最小演示版。来源。

注意： 在此示例中，动画始终从右向左移动，这在点击返回按钮时不自然。本文稍后部分介绍了如何根据导航方向更改动画。

重要提示： 一次只能运行一个视图过渡。如果在一个视图过渡正在运行时启动新的视图过渡，旧的过渡会跳到结束。

---

对多个元素进行转换

在之前的演示中，整个页面都参与了共享轴过渡。这适用于页面的大部分内容，但对于标题似乎不太合适，因为它滑出只是为了再次滑回。

为避免出现这种情况，您可以从网页的其余部分提取页眉，以便单独为其添加动画效果。具体方法是为该元素分配一个 view-transition-name。

.main-header {
  view-transition-name: main-header;
}

view-transition-name 的值可以是任意值（none 除外，这意味着没有过渡名称）。它用于在过渡期间唯一标识相应元素。

注意 ：view-transition-name 必须是唯一的。如果两个渲染元素同时具有相同的 view-transition-name，则会跳过过渡。

结果如下：

添加了固定标题的共享轴转场。最小演示版。来源。

现在，标题会保留在原位并交错淡出。

该 CSS 声明导致伪元素树发生变化：

::view-transition
├─ ::view-transition-group(root)
│  └─ ::view-transition-image-pair(root)
│     ├─ ::view-transition-old(root)
│     └─ ::view-transition-new(root)
└─ ::view-transition-group(main-header)
   └─ ::view-transition-image-pair(main-header)
      ├─ ::view-transition-old(main-header)
      └─ ::view-transition-new(main-header)

现在有两个转换组。一个用于标题，另一个用于其余部分。可以使用 CSS 单独定位这些元素，并采用不同的转场方式。不过，在本例中，main-header 保留了默认转场效果，即交叉淡入淡出。

重要提示： 当浏览器捕获多个过渡组时，不会创建多个视图过渡。相反，浏览器会创建一个涵盖所有过渡组的视图过渡。

好的，默认转场不仅仅是淡入淡出，::view-transition-group 也会进行转场：

• 定位和转换（使用 transform）
• 宽度
• 高度

在此之前，这并不重要，因为 DOM 两端的标头大小和位置发生变化。不过，您也可以提取标题中的文本：

.main-header-text {
  view-transition-name: main-header-text;
  width: fit-content;
}

使用 fit-content 可使元素的大小与文本相同，而不是延伸到剩余的宽度。如果不执行此操作，返回箭头会减小标题文本元素的大小，而非在两页中显示相同大小。

现在，我们有三个部分可以玩：

::view-transition
├─ ::view-transition-group(root)
│  └─ …
├─ ::view-transition-group(main-header)
│  └─ …
└─ ::view-transition-group(main-header-text)
   └─ …

不过，还是使用默认值吧：

滑动标题文本。极简演示。来源。

现在，标题文本会滑过一些有趣的内容，为返回按钮腾出空间。

注意：视图转换使用扁平结构。在真实 DOM 中，标题文本位于标题中。但是，在转换期间，它们各自的 ::view-transition-group 是同级关系。在为容器之间的项目添加动画效果时，这非常有用，因为您无需担心从父元素裁剪。

---

使用 view-transition-class 以相同的方式为多个伪元素添加动画效果

浏览器支持

• 125
• 125
• x
• 

假设您有一个视图过渡效果，其中包含许多卡片，但页面上还包含一个标题。若要为除标题以外的所有卡片添加动画效果，您必须编写一个选择器，分别定位每张卡片。

h1 {
    view-transition-name: title;
}
::view-transition-group(title) {
    animation-timing-function: ease-in-out;
}

#card1 { view-transition-name: card1; }
#card2 { view-transition-name: card2; }
#card3 { view-transition-name: card3; }
#card4 { view-transition-name: card4; }
…
#card20 { view-transition-name: card20; }

::view-transition-group(card1),
::view-transition-group(card2),
::view-transition-group(card3),
::view-transition-group(card4),
…
::view-transition-group(card20) {
    animation-timing-function: var(--bounce);
}

有 20 个元素？因此，您需要编写 20 个选择器。要添加新元素吗？然后，您还需要增大应用动画样式的选择器。扩展性不太理想。

view-transition-class 可用于视图转换伪元素，以应用相同的样式规则。

#card1 { view-transition-name: card1; }
#card2 { view-transition-name: card2; }
#card3 { view-transition-name: card3; }
#card4 { view-transition-name: card4; }
#card5 { view-transition-name: card5; }
…
#card20 { view-transition-name: card20; }

#cards-wrapper > div {
  view-transition-class: card;
}
html::view-transition-group(.card) {
  animation-timing-function: var(--bounce);
}

重要提示： 您必须为每个元素指定一个唯一的 view-transition-name，以便捕获能够正常运行。view-transition-class 会删除重复的动画样式。

以下卡片示例就使用了之前的 CSS 代码段。通过一个选择器，所有卡片（包括新添加的卡片）都会应用相同的时间设置：html::view-transition-group(.card)。

<ph type="x-smartling-placeholder">

</ph>

卡片演示的录制。使用 view-transition-class 时，它会将相同的 animation-timing-function 应用于所有卡片（添加或移除的卡片除外）。

注意：Chrome 团队正在与 CSS 工作组合作，研究如何让您将来能够更轻松、更自动地为元素设置 view-transition-name。

---

调试转换

由于视图转换是基于 CSS 动画构建的，因此 Chrome DevTools 中的 Animations 面板非常适合调试转换。

使用动画面板，您可以暂停下一个动画，然后在动画之间来回拖动。在此期间，您可以在元素面板中找到过渡伪元素。

使用 Chrome DevTools 调试视图转换。

转换元素不必是相同的 DOM 元素

到目前为止，我们使用 view-transition-name 为标题中的文本和标题中的文本创建了单独的转场元素。从概念上讲，DOM 更改前后这些元素是相同的，但您也可以创建不符合这种情况的转换。

例如，您可以为主要视频嵌入代码指定 view-transition-name：

.full-embed {
  view-transition-name: full-embed;
}

然后，在用户点击缩略图时，系统仅在转场期间为其提供相同的 view-transition-name：

thumbnail.onclick = async () => {
  thumbnail.style.viewTransitionName = 'full-embed';

  document.startViewTransition(() => {
    thumbnail.style.viewTransitionName = '';
    updateTheDOMSomehow();
  });
};

结果如下：

一个元素向另一个元素转换。极简演示。来源。

缩略图现在会过渡到主图片中。尽管它们在概念上（以及字面上）是不同的元素，但转场 API 会将它们视为同一元素，因为它们共享相同的 view-transition-name。

此转换的实际代码比前面的示例略复杂一些，因为它还会处理返回缩略图页面的转换。有关完整实现，请参阅源代码。

---

自定义进入和退出过渡

看看下面这个示例：

<ph type="x-smartling-placeholder">

</ph>

进入和退出边栏。最小演示版。来源。

边栏是过渡的一部分：

.sidebar {
  view-transition-name: sidebar;
}

不过，与前面示例中的页眉不同，边栏并未显示在所有页面上。如果这两种状态都有边栏，则过渡伪元素应如下所示：

::view-transition
├─ …other transition groups…
└─ ::view-transition-group(sidebar)
   └─ ::view-transition-image-pair(sidebar)
      ├─ ::view-transition-old(sidebar)
      └─ ::view-transition-new(sidebar)

不过，如果边栏仅在新页面上显示，则不会显示 ::view-transition-old(sidebar) 伪元素。由于边栏没有“旧”图片，因此图片对中只有 ::view-transition-new(sidebar)。同样，如果边栏仅在旧版页面上，则图片对将只有一个 ::view-transition-old(sidebar)。

在上一个演示中，边栏的过渡方式有所不同，具体取决于边栏是在进入、退出还是同时在这两种状态下显示。它通过从右侧滑入并淡入的方式进入，通过向右滑动和淡出退出，在两种状态下都保持在原位。

如需创建特定的进入和退出转场效果，您可以使用 :only-child 伪类定位旧或新伪元素（当它是图片对中的唯一子元素时）：

/* Entry transition */
::view-transition-new(sidebar):only-child {
  animation: 300ms cubic-bezier(0, 0, 0.2, 1) both fade-in,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}

/* Exit transition */
::view-transition-old(sidebar):only-child {
  animation: 150ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-right;
}

在这种情况下，当边栏在两种状态下均显示时，没有特定的过渡，因为默认状态是完美的。

异步 DOM 更新和等待内容

传递给 .startViewTransition() 的回调可以返回一个 Promise，以允许异步 DOM 更新，并等待重要内容准备就绪。

document.startViewTransition(async () => {
  await something;
  await updateTheDOMSomehow();
  await somethingElse;
});

只有在 promise 执行完毕后，转换才会开始。在此期间，页面会冻结，因此应尽量缩短此延迟时间。具体而言，网络提取应在调用 .startViewTransition() 之前完成，此时页面仍可完全互动，而不是作为 .startViewTransition() 回调的一部分执行。

如果您决定等待图片或字体准备就绪，请务必使用较宽的超时设置：

const wait = ms => new Promise(r => setTimeout(r, ms));

document.startViewTransition(async () => {
  updateTheDOMSomehow();

  // Pause for up to 100ms for fonts to be ready:
  await Promise.race([document.fonts.ready, wait(100)]);
});

但在某些情况下，最好完全避免延迟，并使用您已有的内容。

---

充分利用您现有的内容

如果缩略图转换为较大的图片，请执行以下操作：

缩略图转换为较大的图片。试用演示网站。

默认的转场效果是交叉淡出，这意味着缩略图可能会与尚未加载的完整图片交叉淡出。

处理此问题的一种方法是，等待整个图片加载完毕，然后再开始转换。理想情况下，此操作应在调用 .startViewTransition() 之前完成，以便页面保持互动，并且可能会显示旋转图标以向用户指明内容正在加载。但在这种情况下，有一种更好的方法：

::view-transition-old(full-embed),
::view-transition-new(full-embed) {
  /* Prevent the default animation,
  so both views remain opacity:1 throughout the transition */
  animation: none;
  /* Use normal blending,
  so the new view sits on top and obscures the old view */
  mix-blend-mode: normal;
}

现在，缩略图不会淡出，而是位于完整图片下方。也就是说，如果新视图尚未加载，缩略图将在整个转换过程中显示。这意味着转换可以立即开始，并且整个图片可以自行加载。

如果新视图具有透明度，此方法将不起作用，但在本例中，我们知道它没有透明度，因此可以进行此优化。

处理宽高比变化

幸运的是，到目前为止，所有转换都是针对宽高比相同的元素，但情况并不总是如此。如果缩略图的宽高比为 1:1，主图片的宽高比为 16:9，会怎么样？

<ph type="x-smartling-placeholder">

</ph>

一个元素转换到另一个元素，同时宽高比发生变化。极简演示。来源。

在默认转场效果中，该组会以动画形式从前尺寸到后尺寸。旧视图和新视图均采用该组 100% 宽度并自动设置高度，这意味着无论组大小如何，均保持原有的宽高比。

这是一个很好的默认值，但在本例中并不符合预期。因此：

::view-transition-old(full-embed),
::view-transition-new(full-embed) {
  /* Prevent the default animation,
  so both views remain opacity:1 throughout the transition */
  animation: none;
  /* Use normal blending,
  so the new view sits on top and obscures the old view */
  mix-blend-mode: normal;
  /* Make the height the same as the group,
  meaning the view size might not match its aspect-ratio. */
  height: 100%;
  /* Clip any overflow of the view */
  overflow: clip;
}

/* The old view is the thumbnail */
::view-transition-old(full-embed) {
  /* Maintain the aspect ratio of the view,
  by shrinking it to fit within the bounds of the element */
  object-fit: contain;
}

/* The new view is the full image */
::view-transition-new(full-embed) {
  /* Maintain the aspect ratio of the view,
  by growing it to cover the bounds of the element */
  object-fit: cover;
}

这意味着，当宽度扩展时，缩略图会保留在元素的中心，但整个图片会被“取消剪裁”从 1:1 过渡到 16:9

注意 ：为宽度和高度设置动画效果（如 ::view-transition-group 中的示例所示），在按帧运行布局时，通常不认可网页性能圈。不过，对于 View 转换，Chrome 团队计划对其进行优化，以便在大多数情况下在主线程上运行。此优化功能尚未实现。

如需了解详情，请参阅视图过渡：处理宽高比变化

---

使用媒体查询针对不同设备状态更改转换

您可能需要在移动设备和桌面设备上使用不同的转场效果，例如，这个示例在移动设备上从侧面执行完整的幻灯片，但在桌面设备上执行更细微的幻灯片：

<ph type="x-smartling-placeholder">

</ph>

一个元素过渡到另一个元素。极简演示。来源。

这可以通过常规媒体查询来实现：

/* Transitions for mobile */
::view-transition-old(root) {
  animation: 300ms ease-out both full-slide-to-left;
}

::view-transition-new(root) {
  animation: 300ms ease-out both full-slide-from-right;
}

@media (min-width: 500px) {
  /* Overrides for larger displays.
  This is the shared axis transition from earlier in the article. */
  ::view-transition-old(root) {
    animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
      300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
  }

  ::view-transition-new(root) {
    animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in,
      300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
  }
}

根据匹配的媒体查询，您可能还需要更改要为哪些元素分配 view-transition-name。

---

响应“减少运动”偏好设置

用户可以通过操作系统指明他们更喜欢减少动画效果，并且该偏好设置会在 CSS 中公开。

您可以选择阻止这些用户进行任何转换：

@media (prefers-reduced-motion) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none !important;
  }
}

不过，优先使用“减少动作”并不意味着用户不需要任何动作。除了上述代码段，您也可以选择更精细的动画，但该动画仍然可以表达元素与数据流之间的关系。

---

使用视图转换类型处理多种视图转换样式

浏览器支持

• 125
• 125
• x
• 18

有时，从某个特定视图到另一个视图的过渡应有专门定制的过渡。例如，当按分页序列前往下一页或上一页时，您可能想要朝不同方向滑动内容，具体取决于您要前往序列中的更高页面还是更低页面。

分页演示的录制内容。它会根据您要前往的页面使用不同的转场效果。

为此，您可以使用视图转换类型，以便向一个处于活动状态的视图转换分配一种或多种类型。例如，在转到分页序列中的较高页面时，请使用 forwards 类型；当转到较低页面时，请使用 backwards 类型。这些类型仅在捕获或执行过渡时有效，并且每种类型都可以通过 CSS 进行自定义，以使用不同的动画。

如需在同一文档视图转换中使用类型，您需要将 types 传递给 startViewTransition 方法。为此，document.startViewTransition 还接受一个对象：update 是更新 DOM 的回调函数，types 是包含类型的数组。

const direction = determineBackwardsOrForwards();

const t = document.startViewTransition({
  update: updateTheDOMSomehow,
  types: ['slide', direction],
});

注意 ：具有类型的数组会自动转换为类 Set 对象。如需在转场效果实际运行之前更改其内容，请使用其实例方法 clear()、add() 和 delete()

如需响应这些类型，请使用 :active-view-transition-type() 选择器。将要定位到的 type 传递给选择器。这样，您就可以将多个视图转换的样式彼此分开，而不必担心其中一个声明会干扰另一个声明。

由于类型仅在捕获或执行过渡时适用，因此您可以使用选择器针对具有该类型的视图过渡，在元素上设置（或取消设置）view-transition-name。

/* Determine what gets captured when the type is forwards or backwards */
html:active-view-transition-type(forwards, backwards) {
  :root {
    view-transition-name: none;
  }
  article {
    view-transition-name: content;
  }
  .pagination {
    view-transition-name: pagination;
  }
}

/* Animation styles for forwards type only */
html:active-view-transition-type(forwards) {
  &::view-transition-old(content) {
    animation-name: slide-out-to-left;
  }
  &::view-transition-new(content) {
    animation-name: slide-in-from-right;
  }
}

/* Animation styles for backwards type only */
html:active-view-transition-type(backwards) {
  &::view-transition-old(content) {
    animation-name: slide-out-to-right;
  }
  &::view-transition-new(content) {
    animation-name: slide-in-from-left;
  }
}

/* Animation styles for reload type only (using the default root snapshot) */
html:active-view-transition-type(reload) {
  &::view-transition-old(root) {
    animation-name: fade-out, scale-down;
  }
  &::view-transition-new(root) {
    animation-delay: 0.25s;
    animation-name: fade-in, scale-up;
  }
}

在下面的分页演示中，网页内容会根据您要前往的页码向前或向后滑动。这些类型在点击时确定，然后传递到 document.startViewTransition。

如需定位任何活跃的视图转换（无论类型如何），您可以改用 :active-view-transition 伪类选择器。

html:active-view-transition {
    …
}

---

使用视图转换根目录上的类名称处理多个视图转换样式

已废弃：解决此问题的现代方法是使用转换类型。只有在定位到不支持过渡类型的浏览器时，才应使用此类名称方法。

有时，从一种特定类型的视图转换到另一种视图时应该进行专门定制的转场。或“back”导航应不同于“前进”导航导航。

<ph type="x-smartling-placeholder">

</ph>

“返回”时的不同转场效果。最小演示版。来源。

在过渡类型推出之前，处理这些情况的方式是在过渡根上临时设置一个类名称。调用 document.startViewTransition 时，此转场根元素为 <html> 元素，可在 JavaScript 中使用 document.documentElement 访问：

if (isBackNavigation) {
  document.documentElement.classList.add('back-transition');
}

const transition = document.startViewTransition(() =>
  updateTheDOMSomehow(data)
);

try {
  await transition.finished;
} finally {
  document.documentElement.classList.remove('back-transition');
}

为了在过渡完成后移除类，此示例使用了 transition.finished，该 promise 会在过渡到结束状态后解析。API 参考文档中介绍了此对象的其他属性。

注意： 上述代码未定义 isBackNavigation 的确定方式，因为这取决于导航的执行方式。Navigation API 在这里真的非常实用，极简演示中就使用了它。

现在，您可以在 CSS 中使用该类名称来更改转换效果：

/* 'Forward' transitions */
::view-transition-old(root) {
  animation: 90ms cubic-bezier(0.4, 0, 1, 1) both fade-out,
    300ms cubic-bezier(0.4, 0, 0.2, 1) both slide-to-left;
}

::view-transition-new(root) {
  animation: 210ms cubic-bezier(0, 0, 0.2, 1) 90ms both fade-in, 300ms
      cubic-bezier(0.4, 0, 0.2, 1) both slide-from-right;
}

/* Overrides for 'back' transitions */
.back-transition::view-transition-old(root) {
  animation-name: fade-out, slide-to-right;
}

.back-transition::view-transition-new(root) {
  animation-name: fade-in, slide-from-left;
}

与媒体查询一样，这些类的存在也可以用于更改哪些元素会获得 view-transition-name。

---

运行转场而不冻结其他动画

请观看以下视频转换位置演示：

<ph type="x-smartling-placeholder">

</ph>

视频过渡。极简演示。来源。

您发现了什么问题吗？不用担心。此时，它的速度变慢了：

<ph type="x-smartling-placeholder">

</ph>

视频转换，较慢。极简演示。来源。

在过渡期间，视频看起来像是卡住了，然后播放的视频会淡入。这是因为 ::view-transition-old(video) 是旧视图的屏幕截图，而 ::view-transition-new(video) 是新视图的实时图片。

您可以修正此问题，但首先要问问自己它是否值得修正。如果没有看到“问题”当过渡以正常速度播放时，我无需更改它。

如果您真的想解决此问题，请勿显示 ::view-transition-old(video)；直接切换到 ::view-transition-new(video)。为此，您可以替换默认样式和动画：

::view-transition-old(video) {
  /* Don't show the frozen old view */
  display: none;
}

::view-transition-new(video) {
  /* Don't fade the new view in */
  animation: none;
}

这样就大功告成了！

<ph type="x-smartling-placeholder">

</ph>

视频转换，较慢。极简演示。来源。

现在，视频会在整个转换过程中播放。

---

与 Navigation API（及其他框架）集成

视图过渡的指定方式应能够与其他框架或库集成。例如，如果您的单页应用 (SPA) 使用路由器，您可以调整路由器的更新机制，以使用视图转换更新内容。

在此分页演示中提取的以下代码段中，Navigation API 的拦截处理脚本已调整为在支持视图转换时调用 document.startViewTransition。

navigation.addEventListener("navigate", (e) => {
    // Don't intercept if not needed
    if (shouldNotIntercept(e)) return;

    // Intercept the navigation
    e.intercept({
        handler: async () => {
            // Fetch the new content
            const newContent = await fetchNewContent(e.destination.url, {
                signal: e.signal,
            });

            // The UA does not support View Transitions, or the UA
            // already provided a Visual Transition by itself (e.g. swipe back).
            // In either case, update the DOM directly
            if (!document.startViewTransition || e.hasUAVisualTransition) {
                setContent(newContent);
                return;
            }

            // Update the content using a View Transition
            const t = document.startViewTransition(() => {
                setContent(newContent);
            });
        }
    });
});

当用户执行滑动手势进行导航时，部分（但非全部）浏览器会提供自己的转场效果。在这种情况下，您不应触发自己的视图转换，因为这会导致用户体验不佳或令人困惑。用户会看到两个连续运行：一个由浏览器提供，另一个由您提供。

因此，我们建议不要在浏览器提供自己的视觉过渡时开始进行视图过渡。为此，请检查 NavigateEvent 实例的 hasUAVisualTransition 属性的值。如果浏览器提供了视觉过渡效果，则该属性将设置为 true。此 hasUIVisualTransition 属性也存在于 PopStateEvent 实例上。

在上面的代码段中，用于确定是否运行视图转换的检查会考虑此属性。如果不支持同一文档视图转换，或者浏览器已提供自己的转换，则会跳过视图转换。

if (!document.startViewTransition || e.hasUAVisualTransition) {
  setContent(newContent);
  return;
}

在接下来的录音中，用户通过滑动来返回到上一页。左侧的截图不包含对 hasUAVisualTransition 标志的检查。右侧的录制内容包含该检查，因此跳过了手动视图转换，因为浏览器提供了视觉转换。

对同一网站进行比较：未检查 hasUAVisualTransition（左）和已检查 hasUAVisualTransition（右）

注意：默认情况下，Android 版 Chrome 不会为通过滑动手势调用的导航提供视觉转换效果。此功能处于实验阶段，仅在启用 chrome://flags/#back-forward-transitions 功能标志后可用。

---

使用 JavaScript 编写动画

到目前为止，所有转换均使用 CSS 定义，但有时 CSS 并不足以满足需求：

圆形过渡。极简演示。来源。

此过渡的某些部分无法仅使用 CSS 实现：

• 动画从点击位置开始播放。
• 动画结束时，圆圈以距离最远角落的半径为结束。不过，希望未来 CSS 能够实现这一点。

幸运的是，您可以使用 Web 动画 API 创建转场效果！

let lastClick;
addEventListener('click', event => (lastClick = event));

function spaNavigate(data) {
  // Fallback for browsers that don't support this API:
  if (!document.startViewTransition) {
    updateTheDOMSomehow(data);
    return;
  }

  // Get the click position, or fallback to the middle of the screen
  const x = lastClick?.clientX ?? innerWidth / 2;
  const y = lastClick?.clientY ?? innerHeight / 2;
  // Get the distance to the furthest corner
  const endRadius = Math.hypot(
    Math.max(x, innerWidth - x),
    Math.max(y, innerHeight - y)
  );

  // With a transition:
  const transition = document.startViewTransition(() => {
    updateTheDOMSomehow(data);
  });

  // Wait for the pseudo-elements to be created:
  transition.ready.then(() => {
    // Animate the root's new view
    document.documentElement.animate(
      {
        clipPath: [
          `circle(0 at ${x}px ${y}px)`,
          `circle(${endRadius}px at ${x}px ${y}px)`,
        ],
      },
      {
        duration: 500,
        easing: 'ease-in',
        // Specify which pseudo-element to animate
        pseudoElement: '::view-transition-new(root)',
      }
    );
  });
}

此示例使用了 transition.ready，这是一个在成功创建过渡伪元素后解析的 Promise。API 参考文档中介绍了此对象的其他属性。

---

作为增强功能的转场效果

View Transition API 旨在“封装”DOM 更改，并为其创建转场。不过，过渡应被视为一种增强功能，也就是说，如果 DOM 更改成功，但过渡失败，应用不应进入“错误”状态。理想情况下，转换不会失败，但如果失败，则不应该破坏其余的用户体验。

为了将转场效果视为增强功能，请务必谨慎使用转场 promise，以免在转场失败时导致应用抛出异常。

错误做法

async function switchView(data) {
  // Fallback for browsers that don't support this API:
  if (!document.startViewTransition) {
    await updateTheDOM(data);
    return;
  }

  const transition = document.startViewTransition(async () => {
    await updateTheDOM(data);
  });

  await transition.ready;

  document.documentElement.animate(
    {
      clipPath: [`inset(50%)`, `inset(0)`],
    },
    {
      duration: 500,
      easing: 'ease-in',
      pseudoElement: '::view-transition-new(root)',
    }
  );
}

此示例存在的问题是，如果转换无法达到 ready 状态，switchView() 将拒绝，但这并不意味着视图未能切换。DOM 可能已成功更新，但存在重复的 view-transition-name，因此系统跳过了转换。

相反：

正确做法

async function switchView(data) {
  // Fallback for browsers that don't support this API:
  if (!document.startViewTransition) {
    await updateTheDOM(data);
    return;
  }

  const transition = document.startViewTransition(async () => {
    await updateTheDOM(data);
  });

  animateFromMiddle(transition);

  await transition.updateCallbackDone;
}

async function animateFromMiddle(transition) {
  try {
    await transition.ready;

    document.documentElement.animate(
      {
        clipPath: [`inset(50%)`, `inset(0)`],
      },
      {
        duration: 500,
        easing: 'ease-in',
        pseudoElement: '::view-transition-new(root)',
      }
    );
  } catch (err) {
    // You might want to log this error, but it shouldn't break the app
  }
}

此示例使用 transition.updateCallbackDone 等待 DOM 更新，并在更新失败时拒绝更新。如果转换失败，switchView 不再拒绝，它会在 DOM 更新完成时解析，并在更新失败时拒绝。

如果您希望在新视图“稳定”后（即任何动画过渡已完成或跳至结束）解析 switchView，请将 transition.updateCallbackDone 替换为 transition.finished。

---

不是 polyfill，而是…

这不是一个易于实现的功能。不过，在不支持视图转换的浏览器中，此辅助函数可以让事情变得更简单：

function transitionHelper({
  skipTransition = false,
  types = [],
  update,
}) {

  const unsupported = (error) => {
    const updateCallbackDone = Promise.resolve(update()).then(() => {});

    return {
      ready: Promise.reject(Error(error)),
      updateCallbackDone,
      finished: updateCallbackDone,
      skipTransition: () => {},
      types,
    };
  }

  if (skipTransition || !document.startViewTransition) {
    return unsupported('View Transitions are not supported in this browser');
  }

  try {
    const transition = document.startViewTransition({
      update,
      types,
    });

    return transition;
  } catch (e) {
    return unsupported('View Transitions with types are not supported in this browser');
  }
}

它可以按如下方式使用：

function spaNavigate(data) {
  const types = isBackNavigation ? ['back-transition'] : [];

  const transition = transitionHelper({
    update() {
      updateTheDOMSomehow(data);
    },
    types,
  });

  // …
}

在不支持视图过渡的浏览器中，系统仍会调用 updateDOM，但不会提供动画过渡效果。

您还可以提供一些 classNames 以在转换期间添加到 <html>，从而更轻松地根据导航栏类型更改转换。

如果您不希望显示动画，也可以将 true 传递给 skipTransition，即使在支持视图转换的浏览器中也是如此。如果您的网站设有用户偏好设置以停用转换，此设置会非常有用。

---

使用框架

如果您使用的库或框架会抽象化 DOM 更改，那么棘手之处在于如何知道 DOM 更改何时完成。以下是一组在各种框架中使用上述帮助程序的示例。

• React - 此处的关键是 flushSync，它会同步应用一组状态更改。是的，系统会针对使用该 API 发出一条大警告，但 Dan Abramov 向我保证，在本例中使用该 API 是适当的。与 React 和异步代码的往常一样，在使用 startViewTransition 返回的各种 promise 时，应注意以正确的状态运行代码。
• Vue.js - 此处的键是 nextTick，它会在 DOM 更新后执行。
• Svelte - 与 Vue 非常相似，但等待下一次更改的方法为 tick。
• Lit - 这里的关键是组件中的 this.updateComplete 承诺，该承诺会在 DOM 更新后执行。
• Angular - 这里的关键是 applicationRef.tick，它会刷新待处理的 DOM 更改。从 Angular 17 开始，您可以使用 @angular/router 附带的 withViewTransitions。

---

API 参考文档

const viewTransition = document.startViewTransition(update)

启动新的 ViewTransition。

update 是一个函数，在捕获文档的当前状态后会被调用。

然后，当 updateCallback 返回的 promise 执行时，转换将在下一帧中开始。如果 updateCallback 返回的 promise 被拒绝，则会放弃转换。

const viewTransition = document.startViewTransition({ update, types })

使用指定类型启动新的 ViewTransition

捕获文档的当前状态后，系统会调用 update。

types 用于在捕获或执行过渡时为过渡设置活动类型。它最初为空。如需了解详情，请参阅下方的 viewTransition.types。

ViewTransition 的实例成员：

viewTransition.updateCallbackDone

一个在 updateCallback 返回的 promise 执行时执行，在拒绝时拒绝的 promise。

View Transition API 可封装 DOM 更改并创建转场。不过，有时您可能并不关心转换动画是否成功，而只想知道 DOM 是否发生了更改以及何时发生更改。updateCallbackDone 适用于该用例。

viewTransition.ready

一旦创建了转场的伪元素且动画即将开始播放，系统就会执行该 promise。

如果无法开始转换，则会拒绝。这可能是由于配置错误（例如重复的 view-transition-name）或 updateCallback 返回被拒绝的 promise 所致。

这对于使用 JavaScript 为过渡伪元素添加动画很有用。

viewTransition.finished

一旦结束状态对用户完全可见且可互动，即执行的 promise。

只有在 updateCallback 返回已被拒绝的 promise 时，才会拒绝，因为这表示未创建结束状态。

否则，如果转换无法开始或在转换过程中被跳过，系统仍会达到结束状态，因此系统会执行 finished。

viewTransition.types

一个类似于 Set 的对象，用于保存活跃视图过渡的类型。如需操纵这些条目，请使用其实例方法 clear()、add() 和 delete()。

如需在 CSS 中响应特定类型，请对转场根使用 :active-view-transition-type(type) 伪类选择器。

当视图转换完成时，系统会自动清理类型。

viewTransition.skipTransition()

跳过过渡动画部分。

这不会跳过调用 updateCallback，因为 DOM 更改与过渡是分开的。

---

默认样式和过渡参考文档

::view-transition

用于填充视口并包含每个 ::view-transition-group 的根伪元素。

::view-transition-group

定位准确。

在“之前”之间转换 width 和 height和“之后”状态。

在“前”和“前”之间转换 transform和“之后”视口空间四边形。

::view-transition-image-pair

绝对能填满整个群组。

具有 isolation: isolate，用于限制 mix-blend-mode 对旧版和新版视图的影响。

::view-transition-new和::view-transition-old

绝对定位到封装容器的左上角。

填充组宽度的 100%，但高度为自动，因此会保持其宽高比，而不是填充组。

具有 mix-blend-mode: plus-lighter，以允许进行真正的交叉淡化。

旧版视图从 opacity: 1 转换为 opacity: 0。新视图从 opacity: 0 转换为 opacity: 1。

---

反馈

我们衷心期待开发者提供反馈。为此，请在 GitHub 上向 CSS 工作组提交问题，并附上建议和问题。请为问题添加 [css-view-transitions] 前缀。

如果您遇到 bug，请改为提交 Chromium bug。