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

Jad Joubran

发布时间：2025 年 3 月 4 日

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

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

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

浏览器支持和渐进增强

Browser Support

• 116
• 116
• x
• x

Source

在撰写本文时，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 的函数中提前返回。以下代码会检查是否支持 Document PiP，然后打开 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 窗口中打开浏览器预览标签页。除了最大化浏览器预览标签页之外，您还可以将其移至单独的屏幕（如果您有外接显示器），甚至可以将主网应用和浏览器预览标签页重新排列为列布局。

后备

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

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

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

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

---

如您所见，将文档画中画 API 与渐进增强或平滑降级相结合，可为您的 Web 应用开启令人兴奋的新用例。

不要让有限的浏览器支持限制您，同时别忘了提供合适的回退用例。

请参阅 Document PiP 文档，探索此 API 的各种示例和用例。