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

发布时间:2025 年 3 月 4 日

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

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

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

浏览器支持和渐进增强

Browser Support

  • Chrome: 116.
  • Edge: 116.
  • Firefox: not supported.
  • Safari: not supported.

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

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


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

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

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