Picture-in-Picture API

接口

PictureInPictureWindow

表示浮动的视频窗口；包含 width 和 height 属性，以及一个 onresize 事件处理程序属性。

PictureInPictureEvent

表示与画中画相关的事件，包括 enterpictureinpicture、leavepictureinpicture 和 resize。

实例方法

画中画 API 向 HTMLVideoElement 和 Document 接口添加了方法，以允许切换浮动的视频窗口。

HTMLVideoElement 接口的实例方法

HTMLVideoElement.requestPictureInPicture()

请求用户代理将视频置于画中画模式

Document 接口的实例方法

Document.exitPictureInPicture()

请求用户代理将处于画中画模式的元素返回到其原始框中。

实例属性

画中画 API 使用 HTMLVideoElement、Document 和 ShadowRoot 接口的属性来确定是否支持和可用浮动视频窗口模式，画中画模式当前是否处于活动状态，以及哪个视频正在浮动。

HTMLVideoElement 接口的实例属性

HTMLVideoElement.disablePictureInPicture

disablePictureInPicture 属性将向用户代理提供一个提示，告知用户代理不要向用户推荐画中画或自动请求它。

Document 接口的实例属性

Document.pictureInPictureEnabled

pictureInPictureEnabled 属性告诉您是否可以启用画中画模式。如果由于任何原因（例如，"picture-in-picture" 功能已被禁用，或画中画模式不受支持）画中画模式不可用，则此值为 false。

Document 或 ShadowRoot 接口的实例属性

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

pictureInPictureElement 属性告诉您当前在浮动窗口（或 shadow DOM）中显示的 Element 是什么。如果此值为 null，则文档（或 shadow DOM）当前没有节点处于画中画模式。

事件

画中画 API 定义了三个事件，可用于检测画中画模式何时被切换以及浮动视频窗口何时被调整大小。

enterpictureinpicture

当 HTMLVideoElement 进入画中画模式时发送。

leavepictureinpicture

当 HTMLVideoElement 离开画中画模式时发送。

resize

当 PictureInPictureWindow 更改大小时发送。

添加控件

如果通过 媒体会话 API 设置了媒体操作处理程序，则浏览器会将这些操作的相应控件添加到画中画叠加层。例如，如果设置了 "nexttrack" 操作，则可能会在画中画视图中显示一个跳过按钮。不支持添加自定义 HTML 按钮或控件。

控制样式

:picture-in-picture CSS 伪类匹配当前处于画中画模式的视频元素，允许您配置样式表，以便在视频在画中画和传统显示模式之间切换时自动调整内容的大小、样式或布局。

控制访问

可以使用 权限策略控制画中画模式的可用性。画中画模式功能由字符串 "picture-in-picture" 标识，默认允许列表值为 *，这意味着在顶层文档上下文中以及与顶层文档同源的嵌套浏览上下文中都允许画中画模式。

示例

切换画中画模式

在此示例中，我们在网页中有一个 <video> 元素、一个用于切换画中画的 <button>，以及一个用于记录示例相关信息的元素。<button> 元素在确定浏览器支持之前，最初是 disabled 的。

<video
  src="/shared-assets/videos/friday.mp4"
  id="video"
  muted
  controls
  loop
  width="300"></video>

<button id="pip-button" disabled>Toggle PiP</button>
<pre id="log"></pre>

body {
  font:
    14px "Open Sans",
    sans-serif;
  padding: 0.5em;
}

button {
  display: block;
  margin-block: 1rem;
}

我们首先使用 document.pictureInPictureEnabled 检查浏览器是否支持 PiP，如果不支持，我们将该信息记录到 <pre> 元素中。如果浏览器支持，我们就可以启用切换来进入和退出 PiP。

对于控件，对 <button> 元素上的事件侦听器会调用我们定义的 togglePictureInPicture() 函数。在 togglePictureInPicture() 中，一个 if 语句会检查 document 的 pictureInPictureElement 属性的值。

• 如果值为 null，则没有视频在浮动窗口中，因此我们可以请求视频进入画中画模式。我们通过在 <video> 元素上调用 HTMLVideoElement.requestPictureInPicture() 来实现这一点。
• 如果值不是 null，则表示当前有一个元素处于画中画模式。然后，我们可以调用 document.exitPictureInPicture() 将视频恢复到其初始框中，从而退出画中画模式。

const video = document.getElementById("video");
const pipButton = document.getElementById("pip-button");
const log = document.getElementById("log");

if (document.pictureInPictureEnabled) {
  pipButton.removeAttribute("disabled");
} else {
  log.innerText = "PiP not supported. Check browser compatibility for details.";
}

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

pipButton.addEventListener("click", togglePictureInPicture);

:picture-in-picture {
  outline: 5px dashed green;
}

单击“切换 PiP”按钮可让用户在页面内播放视频和在浮动窗口中播放视频之间切换

规范

浏览器兼容性

另见

• HTMLVideoElement.requestPictureInPicture()
• HTMLVideoElement.disablePictureInPicture
• Document.pictureInPictureEnabled
• Document.exitPictureInPicture()
• Document.pictureInPictureElement
• :picture-in-picture
• 文档画中画 API