文档画中画 API

可用性有限

此特性不是基线特性，因为它在一些最广泛使用的浏览器中不起作用。

实验性： 这是一项实验性技术
在生产中使用此技术之前，请仔细检查浏览器兼容性表格。

安全上下文： 此功能仅在安全上下文（HTTPS）中可用，且支持此功能的浏览器数量有限。

文档画中画 API 使得能够打开一个始终置顶的窗口，该窗口可以填充任意 HTML 内容 — 例如带有自定义控件的视频，或显示视频会议参与者的一组流。它扩展了早期的 <video> 的画中画 API，该 API 特别允许将 HTML <video> 元素放入一个始终置顶的窗口。

概念与用法

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

你必须处理两个窗口之间状态信息的共享。
附加的应用窗口不会始终置顶，因此可能被其他窗口隐藏。

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

然而，这个 API 被发现有些局限 — 你只能将单个 <video> 元素放入始终置顶的窗口中，并且只有最小的浏览器生成的控件。为了提供更大的灵活性，引入了文档画中画 API。这允许将任何内容放入始终置顶的窗口中，适用于广泛的用例，包括：

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

通过 Window.documentPictureInPicture 可访问一个代表当前文档上下文的始终置顶画中画窗口的新 DocumentPictureInPicture 对象实例。通过调用 DocumentPictureInPicture.requestWindow() 方法打开画中画窗口，该方法返回一个 Promise，该 Promise 会解析为窗口自身的 Window 对象。

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

画中画窗口浮动在其他窗口的上方。
画中画窗口的生命周期不会超过打开它的窗口。
画中画窗口无法导航。
网站无法设置画中画窗口的位置。
一个浏览器标签页一次最多只能有一个画中画窗口，用户代理可能会进一步限制打开的画中画窗口的总数。

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

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