Picture-in-Picture API
画中画 API(Picture-in-Picture API)允许网站总是在其他窗口之上创建一个浮动的视频,以便用户在其他内容站点或者设备上的应用程序交互时可以继续播放媒体。
[!NOTE] 文档画中画 API 扩展了画中画 API,使其能够将任意 HTML 内容(而不仅仅是视频)呈现在始终置顶的窗口中。
接口
- PictureInPictureWindow
- : 表示浮动的视频窗口;包含 PictureInPictureWindow/width 和 PictureInPictureWindow/height 属性,以及一个 PictureInPictureWindow/onresize 事件处理器属性。
- PictureInPictureEvent
- : 表示画中画相关事件,包括 HTMLVideoElement/enterpictureinpicture_event、HTMLVideoElement/leavepictureinpicture_event 和 PictureInPictureWindow/resize_event。
实例方法
画中画 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属性告诉你当前在浮动窗口(或影子 DOM)显示哪个 Element。如果为null,则此文档(或影子 DOM)没有节点处于画中画模式。
- :
事件
画中画 API 定义了三个事件,它们可以用来检测画中画模式何时被切换或者浮动窗口大小何时被调整。
- HTMLVideoElement.enterpictureinpicture_event
- : 当 HTMLVideoElement 进入画中画模式时触发该事件。
- HTMLVideoElement.leavepictureinpicture_event
- : 当 HTMLVideoElement 离开画中画模式时触发该事件。
- PictureInPictureWindow.resize_event
- : 当 PictureInPictureWindow 大小改变时触发该事件。
添加控件
如果通过媒体会话 API 设置了媒体操作处理器,则浏览器会在画中画叠加层中自动添加相应操作的控件。例如,如果已设置 "nexttrack" 动作,则画中画视图中可能会显示跳过按钮。但该特性不支持添加自定义 HTML 按钮或控件。
控制样式
CSS 伪类 :picture-in-picture 匹配当前进入画中画模式的视频元素,并允许你配置样式表,以便视频在画中画或者传统播放模式来回切换时自动调整内容的大小、样式或布局。
控制访问权限
可以使用权限策略控制画中画的可用性。全屏模式的特性由字符串 "picture-in-picture" 标识,默认的允许列表的值是 *,意味着在顶级文档上下文以及从与最顶层文档相同的来源加载的嵌套浏览上下文中允许画中画模式。
示例
在此示例中,视频被展示在 web 页面。点击下面的按钮可以让用户切换浮动视频窗口。
dom-examples/picture-in-picture/index.html
切换画中画模式
当使用者点击“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() 来实现。
规范
浏览器兼容性
参见
- HTMLVideoElement.requestPictureInPicture()
- HTMLVideoElement.disablePictureInPicture
- Document.pictureInPictureEnabled
- Document.exitPictureInPicture()
- Document.pictureInPictureElement
- :picture-in-picture
- 文档画中画 API
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
