画中画(Picture-in-Picture)API

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

接口

PictureInPictureWindow

表示浮动的视频窗口;包含 width (en-US)height (en-US) 属性,以及一个 onresize (en-US) 事件处理器属性。

方法

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

HTMLVideoElement 接口的方法

HTMLVideoElement.requestPictureInPicture()

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

Document 接口的方法

Document.exitPictureInPicture()

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

属性

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

HTMLVideoElement 接口的属性

HTMLVideoElement.autoPictureInPicture

当用户切换标签页和(或)应用程序时,autoPictureInPicture 属性将自动进入或离开视频元素的画中画模式。

HTMLVideoElement.disablePictureInPicture

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

Document 接口的属性

Document.pictureInPictureEnabled

pictureInPictureEnabled 属性告诉你是否可以使用画中画模式。如果画中画模式因任何原因不可用(例如"画中画"功能 不被接受,或者不支持画中画模式),则是 false

Document 或 ShadowRoot 接口的属性

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement (en-US)

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

事件

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

enterpictureinpicture

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

leavepictureinpicture

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

resize (en-US)

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

控制样式

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

控制访问权限

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

参见使用 Feature Policy,了解关于使用 Feature Policy 控制对 API 访问的更多信息。

示例

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

切换画中画模式

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

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

参见