画中画 API

Limited availability

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

画中画 API(Picture-in-Picture API)允许网站总是在其他窗口之上创建一个浮动的视频,以便用户在其他内容站点或者设备上的应用程序交互时可以继续播放媒体。

备注: 文档画中画 API 扩展了画中画 API,使其能够将任意 HTML 内容(而不仅仅是视频)呈现在始终置顶的窗口中。

接口

PictureInPictureWindow

表示浮动的视频窗口;包含 widthheight 属性,以及一个 onresize 事件处理器属性。

PictureInPictureEvent

表示画中画相关事件,包括 enterpictureinpictureleavepictureinpictureresize

实例方法

画中画 API 添加了 HTMLVideoElementDocument 接口的方法,以便允许切换浮动视频窗口。

HTMLVideoElement 接口上的实例方法

HTMLVideoElement.requestPictureInPicture()

请求用户代理将视频切换为画中画模式。

Document 接口上的实例方法

Document.exitPictureInPicture()

请求用户代理将元素由画中画模式切换回到它的原始盒子。

实例属性

画中画 API 添加了 HTMLVideoElementDocumentShadowRoot 接口的属性,这些属性用于决定浮动的视频窗口是否是受支持和可用的、当前画中画模式是否处于激活状态并且哪个视频是浮动的。

HTMLVideoElement 接口上的实例属性

HTMLVideoElement.disablePictureInPicture

disablePictureInPicture 属性将指示用户代理是否应该向用户建议画中画的功能。

Document 接口上的实例属性

Document.pictureInPictureEnabled

pictureInPictureEnabled 属性告诉你是否可以使用画中画模式。如果画中画模式因任何原因不可用(例如 "picture-in-picture" 特性不被允许,或者不支持画中画模式),则是 false

Document 或 ShadowRoot 接口上的实例属性

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

pictureInPictureElement 属性告诉你当前在浮动窗口(或影子 DOM)显示哪个 Element。如果为 null,则此文档(或影子 DOM)没有节点处于画中画模式。

事件

画中画 API 定义了三个事件,它们可以用来检测画中画模式何时被切换或者浮动窗口大小何时被调整。

enterpictureinpicture

HTMLVideoElement 进入画中画模式时触发该事件。

leavepictureinpicture

HTMLVideoElement 离开画中画模式时触发该事件。

resize

PictureInPictureWindow 大小改变时触发该事件。

添加控件

如果通过媒体会话 API 设置了媒体操作处理器,则浏览器会在画中画叠加层中自动添加相应操作的控件。例如,如果已设置 "nexttrack" 动作,则画中画视图中可能会显示跳过按钮。但该特性不支持添加自定义 HTML 按钮或控件。

控制样式

CSS 伪类 :picture-in-picture 匹配当前进入画中画模式的视频元素,并允许你配置样式表,以便视频在画中画或者传统播放模式来回切换时自动调整内容的大小、样式或布局。

控制访问权限

可以使用权限策略控制画中画的可用性。全屏模式的特性由字符串 "picture-in-picture" 标识,默认的允许列表的值是 *,意味着在顶级文档上下文以及从与最顶层文档相同的来源加载的嵌套浏览上下文中允许画中画模式。

示例

在此示例中,视频被展示在 web 页面。点击下面的按钮可以让用户切换浮动视频窗口。

切换画中画模式

当使用者点击“Toggle Picture-in-Picture”按钮时,这段代码将会由一个点击处理器调用:

js
function togglePictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  } else {
    if (document.pictureInPictureEnabled) {
      video.requestPictureInPicture();
    }
  }
}

该块首先会查询 document pictureInPictureElement 属性的值。

如果值不是 null,则它是当前处于画中画模式并在浮动窗口的元素。我们调用 document.exitPictureInPicture() 将视频带进它初始的盒子。

如果值是 null,浮动窗口没有视频。所以我们可以请求视频进入画中画模式。我们可以在 <video> 元素上调用 HTMLVideoElement.requestPictureInPicture() 来实现。

规范

Specification
Picture-in-Picture
# interface-picture-in-picture-window

浏览器兼容性

BCD tables only load in the browser

参见