大网数据广告活动
Web 标准与前端开发

DocumentPictureInPicture:requestWindow() 方法

· 52CE 我爱测

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

Document Picture-in-Picture API

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

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

语法

requestWindow()
requestWindow(options)

参数

  • options
    • : 包含以下属性的选项对象:
      • disallowReturnToOpener

        • : 布尔值。设置为 true 时,此选项提示浏览器不应显示允许用户返回原始标签页并关闭画中画窗口的 UI 控件。默认为 false。例如,在 Chrome 实现此功能时,提供的 UI 控件是画中画窗口顶部栏中的“返回标签页”按钮:

          浏览器窗口中包含一个嵌入式视频播放器和多个控制按钮,顶部栏中有一个返回标签页按钮,以红色框突出显示

      • height

        • : 一个非负数,表示要为画中画窗口的视口设置的高度(以像素为单位)。默认值为 0。
      • preferInitialWindowPlacement

        • : 布尔值,默认为 false。当设置为 true 时,画中画窗口在关闭并重新打开时总是回到最初打开的位置和大小。相反,如果 preferInitialWindowPlacement 为 false,画中画窗口的大小和位置将在关闭和重新打开时被记住——它将重新打开到之前的位置和大小,例如由用户设置。
      • width

        • : 一个非负数,表示要为画中画窗口的视口设置的宽度(以像素为单位)。默认值为 0。

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

返回值

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

异常

  • NotSupportedError DOMException
    • : 如果 API 已被明确禁用(例如通过浏览器设置),则抛出此异常。
  • NotAllowedError DOMException
    • : 在符合以下条件时抛出此异常:
      • requestWindow() 不是从顶级 window 对象调用的。
      • requestWindow() 是从画中画窗口的 window 对象调用的(即 DocumentPictureInPicture.window)。
      • 调用 requestWindow() 时不满足Transient_activation。
  • RangeError DOMException
    • : 如果仅设置了 height 和 width 中的一个,或者 height 和 width 设置为负值,则抛出。

示例

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

// ...

// 打开画中画窗口并设置所有选项
const pipWindow = await window.documentPictureInPicture.requestWindow({
  width: videoPlayer.clientWidth,
  height: videoPlayer.clientHeight,
  disallowReturnToOpener: true,
  preferInitialWindowPlacement: true,
});

// ...

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。