View Transition API 做列表到详情过渡的渐进增强

列表进入详情时，最稳妥的做法不是把导航完全交给动画，而是让“更新内容”本身先能正常完成：支持 View Transition API 的浏览器用 document.startViewTransition(update) 包住这次 DOM 更新，不支持时直接执行同一个 update。这样动画是增强层，列表、详情和返回操作仍是基础功能。

一、先选定列表到详情的过渡边界

如果列表和详情由同一个前端路由渲染，优先采用 SPA 方案：点击卡片后更新状态、修改历史记录，再让浏览器采集新旧视图。若列表页与详情页是两个同源 HTML 文档，则可以选择 MPA 方案，当前页和目标页都加入 @view-transition。跨源页面不能直接套用这个 MPA 选择加入规则。

二、用 startViewTransition 包住 DOM 更新

关键是把“取得详情数据、渲染详情、写入历史记录”收束到一个更新函数里。下面的示例假定 renderDetail 会更新详情区域；它返回 Promise 时，浏览器会等更新回调完成后再开始过渡。

async function openDetail(id, card) {
  // 让同一张封面在列表和详情之间使用同一个过渡名称。
  card.style.viewTransitionName = `item-cover-${id}`;

  const update = async () => {
    // 先取得数据并更新详情，再写入历史记录，失败时不改变地址。
    const item = await fetchItem(id);
    await renderDetail(item);
    history.pushState({ id }, "", `/items/${encodeURIComponent(id)}`);
  };

  // 不支持 API 时仍然执行同一个更新函数，保证渐进增强。
  if (!document.startViewTransition) {
    await update();
    return;
  }

  document.startViewTransition(update);
}

真实项目里应在渲染完成后给详情主图设置同名的 view-transition-name，并在下一次打开其他卡片前清理旧名称。名称不能同时绑定多个同作用域元素，否则浏览器无法确定要配对的快照。

三、用 CSS 控制共享元素和动画边界

默认效果通常是淡入淡出。只想让封面移动，其余内容保持轻微淡入，可以给共享元素单独命名，再覆盖对应的伪元素动画。

/* 只有当前卡片封面参与共享元素过渡，避免整页一起移动。 */
.item-card[data-active="true"] .item-card__cover,
.detail__cover {
  view-transition-name: item-cover-active;
}

/* 让共享封面更快落位，正文仍使用浏览器默认淡入淡出。 */
::view-transition-old(item-cover-active),
::view-transition-new(item-cover-active) {
  animation-duration: 260ms;
  animation-timing-function: ease-out;
}

/* 用户偏好减少动态效果时，保留内容切换但取消动画。 */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none;
  }
}

这里的 CSS 只描述动画层，不承担数据更新。若用户快速连续点击，应用层仍需禁用重复触发或取消上一次请求；不要把网络等待无限期塞进视觉过渡。

四、失败回退与验收清单

把下面几项作为上线前检查：一是关闭 API 后，点击卡片仍能到达详情；二是 fetchItem 或渲染失败时不应先推入错误地址；三是返回按钮能恢复列表状态；四是同一时刻只有一组共享名称；五是减少动态效果时仍保留清晰的焦点和标题变化。

如果采用 MPA，两个同源文档都放入以下 CSS；不支持的浏览器会继续按普通链接完成导航。

/* MPA 只选择加入同源跨文档过渡，不改变链接本身的导航语义。 */
@view-transition {
  navigation: auto;
}

相关问题

为什么包了 startViewTransition 却没有动画？

先确认更新回调没有抛错，并检查页面是否在后台标签页；再确认元素的过渡名称唯一且浏览器支持该 API。

列表和详情必须使用相同的图片尺寸吗？

不必相同，但比例差异过大时会产生明显拉伸感。优先保持主体位置和宽高比稳定，再用 CSS 处理容器裁切。

SPA 和 MPA 应该选哪个？

已有同页状态管理时选 SPA；希望保留普通链接、独立文档和服务端渲染时选 MPA，并确认页面同源。