Picture-in-Picture API
HTMLVideoElement 接口提供的 requestPictureInPicture() 方法会发出异步请求,并以画中画的模式显示视频。
该方法不能保证视频进入画中画。如果授予了进入画中画的权限,则返回的 Promise 会兑现,且视频将收到一个 HTMLVideoElement.enterpictureinpicture_event 事件,来表示它现在处于画中画状态。
语法
requestPictureInPicture()
参数
无。
返回值
Promise,会兑现一个可用于监听用户何时调整该浮动窗口的大小的 PictureInPictureWindow 对象。
异常
NotSupportedErrorDOMException- : 如果该特性不受支持(例如,被用户偏好设置或平台限制禁用),则抛出该异常。
SecurityErrorDOMException- : 如果该功能被权限策略阻止,则抛出该异常。
InvalidStateErrorDOMException- : 如果视频元素的
readState为HAVE_NOTHING,或者视频元素没有视频轨道,或者视频元素的disablePictureInPicture属性为true,则抛出该异常。
- : 如果视频元素的
NotAllowedErrorDOMException- : 如果
document.pictureInPictureElement为null且文档没有transient activation,则抛出错误。
- : 如果
安全
需要瞬态用户激活。用户必须与页面或 UI 元素进行交互,才能使用此特性。
示例
本示例请求视频进入画中画模式,并设置事件监听以处理窗口大小的调整。
function enterPictureInPicture() {
videoElement.requestPictureInPicture().then((pictureInPictureWindow) => {
pictureInPictureWindow.addEventListener(
"resize",
() => onPipWindowResize(),
false,
);
});
}
规范
浏览器兼容性
参见
- video 元素
- HTMLVideoElement.disablePictureInPicture
- Document.pictureInPictureEnabled
- Document.exitPictureInPicture()
- Document.pictureInPictureElement
- :picture-in-picture
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
