画中画 API

PictureInPictureWindow

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

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

HTMLVideoElement.requestPictureInPicture()

请求用户代理将视频进入画中画模式

Document.exitPictureInPicture()

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

画中画 API 增强了 HTMLVideoElement、Document 和 ShadowRoot 接口，并添加了属性，这些属性可用于确定是否支持和可用浮动视频窗口模式，是否当前处于画中画模式，以及哪个视频是浮动的。

HTMLVideoElement.disablePictureInPicture

disablePictureInPicture 属性将向用户代理提供提示，以不向用户建议画中画功能或自动请求画中画功能。

Document.pictureInPictureEnabled

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

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

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

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

enterpictureinpicture

在 HTMLVideoElement 进入画中画模式时发送给它。

leavepictureinpicture

在 HTMLVideoElement 退出画中画模式时发送给它。

resize

在 PictureInPictureWindow 大小改变时发送给它。

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

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

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

在此示例中，视频在网页中呈现。单击下面的按钮，用户可以切换浮动视频窗口。

当用户单击“切换画中画”按钮时，此代码由单击处理程序调用

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

此代码块首先查看 document 的 pictureInPictureElement 属性的值。

如果该值不为 null，则它是当前处于画中画模式的元素，即在一个浮动窗口中。我们调用 document.exitPictureInPicture() 将视频带回其初始框。

如果该值为 null，则没有视频在浮动窗口中。因此，我们可以请求视频进入画中画模式。我们通过在 <video> 元素上调用 HTMLVideoElement.requestPictureInPicture() 来实现。

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