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 Specification
# dom-window-documentpictureinpicture

浏览器兼容性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
documentPictureInPicture
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Experimental. Expect behavior to change in the future.