DocumentPictureInPicture：requestWindow() 方法

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

实验性: 这是一项实验性技术
在将其用于生产之前，请仔细检查浏览器兼容性表格。

安全上下文: 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

DocumentPictureInPicture 接口的 requestWindow() 方法为当前主浏览上下文打开画中画窗口。它返回一个 Promise，其兑现一个 Window 实例，表示画中画窗口内的浏览上下文。

requestWindow() 方法需要瞬态激活，也就是说，它必须在响应鼠标单击或按钮按下等用户操作时调用。

语法

js
requestWindow()
requestWindow(options)

参数

options 可选

包含以下属性的选项对象：

height

一个非负数，表示要为画中画窗口的视口设置的高度（以像素为单位）。如果未指定 options，则使用默认值 0。

width

一个非负数，表示要为画中画窗口的视口设置的宽度（以像素为单位）。如果未指定 options，则使用默认值 0。

备注： 如果指定了其中一个选项，则必须同时指定另一个选项，否则会抛出错误。如果两个值均未指定、指定为 0 或设置过大，则浏览器将根据需要限制或忽略这些值以提供合理的用户体验。限制的大小将根据浏览器实现、显示器尺寸和其他因素而有所不同。

返回值

一个兑现 Window 对象实例的 Promise，该实例代表画中画窗口内的浏览上下文。

异常

NotSupportedError DOMException

如果 API 已被明确禁用（例如通过浏览器设置），则抛出此异常。

NotAllowedError DOMException

在符合以下条件时抛出此异常：

  • requestWindow() 不是从顶级 window 对象调用的。
  • requestWindow() 是从画中画窗口的 window 对象调用的（即 DocumentPictureInPicture.window）。
  • 调用 requestWindow() 时不满足瞬态激活。
RangeError DOMException

如果仅设置了 height 和 width 中的一个，或者 height 和 width 设置为负值，则抛出。

示例

js
const videoPlayer = document.getElementById("player");

// ...

// 打开画中画窗口。
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
});

// ...

规范

Specification
Document Picture-in-Picture Specification
# dom-documentpictureinpicture-requestwindow

浏览器兼容性

BCD tables only load in the browser

参见