Document Picture-in-Picture API

除了运行 Web 应用的主窗口之外，为 Web 应用提供不同的窗口通常很有帮助。你可能希望在浏览其他窗口的同时保持特定应用内容的可见性，或者你可能希望为该内容提供自己的空间，同时保持主应用窗口可用以显示其他内容。你可以通过打开一个常规的新浏览器窗口来处理此问题，但这有两个主要问题：

1. 你必须处理两个窗口之间的状态信息共享。
2. 附加应用窗口并不总是位于顶层，因此可能会被其他窗口隐藏。

为了解决这些问题，web 浏览器引入了 API，允许应用生成属于同一会话且始终在顶层的窗口。第一个公认的用例是让视频内容在单独的窗口中播放，以便用户可以在查看其他内容的同时继续观看视频。这是使用 <video> 的 Picture-in-Picture API 来处理的，它直接用于将 <video> 元素放入单独的窗口中。

然而，我们发现此 API 存在一定限制——你只能将单个 <video> 元素放入始终在顶层的窗口中，并且浏览器生成的控件数量极少。Document Picture-in-Picture API 的引入带来来更大的灵活性。这允许将任何内容放置在始终在顶层的窗口中，以用于各种用例，包括：

• 始终位于顶层的自定义视频播放器，显示一个或多个具有自定义控件和样式的视频。
• 视频会议系统，允许用户始终看到其他参与者的串流，以及用于呈现内容、静音、结束通话等的控件。
• 始终可见的生产力工具，如计时器、笔记、待办事项列表、信使工具等。
• 一个单独的窗口，用于保存其他内容，同时保持主应用窗口整洁。例如，你可能正在运行一个动作或角色扮演游戏，你想在另一个窗口中显示游戏控件、说明或故事设定，同时保持主窗口空闲以显示游戏位置和地图。

可通过 Window.documentPictureInPicture 属性获取新的 DocumentPictureInPicture 对象实例，该实例表示当前文档上下文中始终处于顶层的画中画窗口。画中画窗口通过调用 DocumentPictureInPicture.requestWindow() 方法打开，该方法返回一个 Promise，其会兑现一个画中画窗口自己的 Window 对象。

画中画窗口类似于通过 Window.open() 打开的空白同源窗口，但有一些区别：

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

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

详细使用指南请参阅使用 Document Picture-in-Picture API。

DocumentPictureInPicture

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

DocumentPictureInPictureEvent

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

Window.documentPictureInPicture

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

display-mode，picture-in-picture 值

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

请参阅 Document Picture-in-Picture API 示例获取完整的可运行演示（另请参阅完整的源代码）。