文档画中画 API

除了运行应用程序的主窗口之外，让 Web 应用程序拥有另一个窗口通常很有帮助。您可能希望在保持特定应用程序内容可见的情况下浏览其他窗口，或者您可能希望为该内容提供自己的空间，同时将主应用程序窗口释放出来以显示其他内容。您可以通过打开一个常规的新浏览器窗口来处理这个问题，但这有两个主要问题

1. 您必须处理两个窗口之间的状态信息共享。
2. 额外的应用程序窗口并不总是保持在最前面，因此可能会被其他窗口隐藏。

为了解决这些问题，Web 浏览器引入了 API，允许应用程序生成一个始终位于顶部的窗口，该窗口是同一会话的一部分。第一个公认的用例是将视频内容保持在单独的窗口中播放，以便用户在查看其他内容时可以继续观看。这是使用 <video> 的画中画 API 处理的，该 API 直接用于 <video> 元素，将其放置到单独的窗口中。

但是，人们发现此 API 有些限制 - 您只能将一个 <video> 元素放入始终位于顶部的窗口中，并且浏览器生成的控件很少。为了提供更多灵活性，引入了 **文档画中画 API**。这允许将任何内容放置在始终位于顶部的窗口中，以用于各种用例，包括

• 一个始终位于顶部的自定义视频播放器，显示一个或多个带有自定义控件和样式的视频。
• 一个视频会议系统，允许用户始终看到其他参与者的视频流，以及用于呈现内容、静音、结束通话等的控件。
• 始终可见的生产力工具，例如计时器、笔记、待办事项列表、消息工具等。
• 一个单独的窗口，用于在保持主应用程序窗口整洁的情况下保存额外内容。例如，您可能有一个动作或角色扮演游戏正在运行，您希望在额外的窗口中显示游戏控件、说明或传说，同时将主窗口保留用于显示游戏位置和地图。

一个新的 DocumentPictureInPicture 对象实例，它代表当前文档上下文中始终位于顶部的画中画窗口，可以通过 Window.documentPictureInPicture 获取。通过调用 DocumentPictureInPicture.requestWindow() 方法打开画中画窗口，该方法返回一个 Promise，该方法将使用窗口自身的 Window 对象来完成。

画中画窗口类似于通过 Window.open() 打开的空白同源窗口，但也有一些不同之处

• 画中画窗口漂浮在其他窗口之上。
• 画中画窗口永远不会超过打开窗口的生命周期。
• 画中画窗口不可导航。
• 画中画窗口的位置不可由网站设置。
• 画中画窗口每个浏览器标签一次只能有一个，用户代理可能会进一步限制打开的画中画窗口的全局数量。

除此之外，您可以根据需要操作画中画窗口的 Window 实例，例如将您要显示的内容附加到其 DOM，并将样式表复制到其中，以便附加的内容将与它在主窗口中的样式相同。您还可以关闭画中画窗口（通过单击浏览器提供的控件，或通过在其上运行 Window.close()），然后使用标准的 pagehide 对其关闭做出反应。关闭时，您需要将它正在显示的内容放回主应用程序窗口。

有关详细的使用指南，请参阅 使用文档画中画 API。

DocumentPictureInPicture

创建和处理文档画中画窗口的入口点。

DocumentPictureInPictureEvent

enter 事件的事件对象，当画中画窗口打开时触发。

Window.documentPictureInPicture

返回对当前文档上下文中 DocumentPictureInPicture 对象的引用。

display-mode，picture-in-picture 值

一个 CSS 媒体特征 值，允许开发人员根据文档是否以画中画模式显示将 CSS 应用于文档。

有关完整的演示，请参阅 文档画中画 API 示例（另请参阅完整的 源代码）。