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

Jad Joubran

发布时间：2025 年 3 月 4 日

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

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

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

浏览器支持和渐进式增强

在撰写本文时，Document Picture-in-Picture API 的可用性有限。

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

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

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

LearnHTMLCSS.online 是一个互动式学习平台，可帮助您学习语义化且易于访问的 HTML 和 CSS。它提供交互式文本编辑器和浏览器预览窗口。

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

作为学生，您有时可能希望最大化浏览器预览窗口。这是添加对 Document Picture-in-Picture API 的支持的绝佳机会。

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

const isPipSupported = "documentPictureInPicture" in window;

现在，您可以使用此变量来封装任何 documentPictureInPicture 调用，或者从依赖于 Document 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 时，后备行为通过 Maximize 和 Minimize 进行描述。

如您所见，Document Picture-in-Picture API 与渐进增强或优雅降级相结合，可为您的 Web 应用带来令人兴奋的新用例。

不要让有限的浏览器支持限制了您的想象力，也别忘了准备一个不错的回退用例。

您可以查看文档：Document PiP，了解此 API 的各种示例和使用情形。