利用文档画中画 API 实现令人兴奋的应用场景

Jad Joubran

发布时间：2025 年 3 月 4 日

文档画中画 API（文档 PiP API）可让 Web 应用打开一个浮动且始终位于顶部的窗口（画中画窗口），该窗口可以显示任何任意 HTML 内容。

此 API 基于 画中画 API 构建，可让您在 PiP 窗口中继续观看视频。<video>

由于文档 PiP API 可以显示任何任意 HTML 内容，因此您可以使用它来解锁令人兴奋的新用例。

浏览器支持和渐进增强

Browser Support

• 116
• 116
• 151
• x

Source

在撰写本文时，文档画中画 API 的适用范围有限。

不过，这不应妨碍您将其与 渐进增强或 优雅降级搭配使用。

在规划应用场景时，请务必将其视为渐进增强，而不是标准功能。在本文中，您将看到一个优雅降级的示例。

利用文档 PiP API 提升学习者的用户体验

LearnHTMLCSS.online 是一个互动式学习平台，用于教授语义和无障碍 HTML 和 CSS。它提供了一个互动式文本编辑器和浏览器预览窗口。

以下截屏视频显示了应用的布局；屏幕分为两列。 第一列包含代码编辑器。 第二列包含标签页式布局。默认情况下，用户可以看到挑战的说明，并且可以点击浏览器 标签页来查看实时预览。

作为学生，您有时可能希望最大化浏览器预览窗口。 这是一个添加对文档画中画 API 的支持的绝佳机会。

如需实现此功能，请先检查浏览器支持情况：

const isPipSupported = "documentPictureInPicture" in window;

现在，您可以使用此变量来封装任何 documentPictureInPicture 调用，或者提前从依赖于文档 PiP 的函数返回。以下代码检查是否支持文档 PiP，然后打开文档 PiP 窗口。

async function initDocumentPip() {
  if (!isPipSupported) {
    return false;
  }

  const pipWindow = await documentPictureInPicture.requestWindow({
    width: window.innerWidth,
    height: window.innerHeight,
  });
}

您可以根据用例为窗口指定任意宽度和高度。 您可以尝试匹配特定元素、当前文档，甚至提供固定值。

到目前为止，您有一个空文档。现在，您需要为其填充内容。

// htmlCode is the HTML code of the challenge
pipWindow.document.documentElement.innerHTML = htmlCode;

对于包含 CSS 代码的挑战，您还需要同步 CSS。

大功告成！现在，您有了一个最大化按钮，该按钮会在单独的 PiP 窗口中打开。除了最大化浏览器预览标签页之外，您还可以将其移至单独的屏幕（如果您有外接显示器），甚至可以在列布局中重新排列主 Web 应用和浏览器预览标签页。

后备

请注意，此 API 的适用范围有限。 在不支持此 API 的浏览器和设备上，您需要提供后备（优雅降级）行为。

我们可以让最大化按钮占据当前 Web 应用的所有剩余空间，而不是让最大化按钮拉出整个浏览器预览标签页。

在不同的浏览器中尝试此行为：https://learnhtmlcss.online/app.html?id=2096

别忘了注意提示中的小细节。当 isPipSupported 为 true 时，最大化/最小化按钮的提示会在 进入画中画 和 退出画中画 之间切换。 另一方面，当 isPipSupported 为 false 时，后备行为会使用 最大化 和 最小化 进行描述。

---

如您所见，文档画中画 API 与渐进增强或优雅降级功能相结合，可以为您的 Web 应用解锁令人兴奋的新用例。

不要让有限的浏览器支持限制您，并且别忘了拥有一个不错的后备用例。

查看文档 PiP 的文档，了解此 API 的各种示例和用例。