Document Picture-in-Picture API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

实验性: 这是一项实验性技术
在将其用于生产之前,请仔细检查浏览器兼容性表格

安全上下文: 此项功能仅在一些支持的浏览器安全上下文(HTTPS)中可用。

Document Picture-in-Picture API 可以打开一个始终在顶层的窗口,该窗口可以填充任意 HTML 内容——例如带有自定义控件的视频或一组显示视频会议参与者的串流。它扩展了早期的 <video> 的 Picture-in-Picture API,该 API 专用于将 HTML <video> 元素放入始终在顶层的窗口中。

概念和用法

除了运行 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 对象的引用。

CSS 补充

display-modepicture-in-picture

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

示例

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

规范

Specification
Document Picture-in-Picture
# dom-window-documentpictureinpicture

浏览器兼容性

BCD tables only load in the browser