能力中的 API
Window Management API
发布于 更新于
Window Management API 告诉页面设备是否有多块屏幕以及各自的位置,让页面把窗口放到指定屏幕上。window.screen.isExtended 不弹提示,只返回一个布尔值,说明是否有多块屏幕,给不出具体数量。要获取详细信息,调用 window.getScreenDetails() 请求 window-management 权限。
返回的 ScreenDetails 对象中,screens 数组为每块显示器保存一个 ScreenDetailed。坐标以多屏原点为参照,可用于 window.open() 的 features;requestFullscreen({ screen }) 也可指定显示器。
Chrome 100 在桌面端发布了 getScreenDetails()、Screen.isExtended 和 ScreenDetailed;Edge 与 Opera 继承该实现。Android 版 Chrome 暴露 getScreenDetails() 和 isExtended,BCD 把那里的 ScreenDetailed 标为不支持。Firefox 和 Safari 任何版本都没有实现(BCD api.Window.getScreenDetails)。所有接口都带 [SecureContext]。
window.screen.isExtended
window.getScreenDetails()
screenDetails.screensscreenDetails.currentScreen
element.requestFullscreen({ screen: screenDetailed })isExtended 是现有 Screen 接口上的同步 boolean。getScreenDetails() 返回 Promise<ScreenDetails>;同一个 Window 多次调用会得到同一个 ScreenDetails 对象。显示器增减会触发 screenschange;窗口移到另一块显示器,或所在屏幕属性变化,会触发 currentscreenchange。ScreenDetailed 继承自 Screen,所以除下表成员外还有 width、height、availWidth、availHeight、colorDepth 和 orientation。
getScreenDetails() 不接受参数。返回对象的成员见表;现有方法上新增的选项只有 FullscreenOptions 的 screen 成员,另有 setResizable(resizable) 接受一个布尔值。
| 成员 | 类型 | 必填 | 说明 |
|---|---|---|---|
ScreenDetails.screens |
FrozenArray<ScreenDetailed> |
只读 | 全部屏幕,先按 left 再按 top 排序。集合变化时换成新数组。 |
ScreenDetails.currentScreen |
ScreenDetailed |
只读 | 窗口所在的屏幕;与 screens 中的某一项 ===,所以 screens.find(s => s !== currentScreen) 选出的是当前屏幕之外的一块屏幕。它不一定是副屏,需要时用 isPrimary 判断。 |
ScreenDetailed.left、ScreenDetailed.top |
long |
只读 | 多屏原点到该屏幕左边缘、上边缘的距离,单位 CSS 像素。 |
ScreenDetailed.availLeft、ScreenDetailed.availTop |
long |
只读 | 同上,但针对排除任务栏与 Dock 的可用区域。在 window.open() 的 features 里用作 left/top。 |
ScreenDetailed.isPrimary |
boolean |
只读 | 操作系统指定的主显示器为 true。 |
ScreenDetailed.isInternal |
boolean |
只读 | 笔记本屏幕之类的内置面板为 true,外接显示器为 false。 |
ScreenDetailed.devicePixelRatio |
float |
只读 | 该屏幕的物理像素与 CSS 像素之比,可能不同于 window.devicePixelRatio。 |
ScreenDetailed.label |
DOMString |
只读 | 操作系统提供的名称,例如 "Built-in Retina Display" 或 "DELL U2720Q";可能为空。 |
FullscreenOptions.screen |
ScreenDetailed |
否 | 要求 requestFullscreen() 先把窗口移到该屏幕。浏览器可以转而尊重用户偏好。 |
规范为 getScreenDetails() 定义了一种拒绝名称,并在相关的 minimize()、maximize()、restore() 和 setResizable() 方法中复用(见 getScreenDetails() 方法(w3.org))。
| 异常 | 条件 |
|---|---|
NotAllowedError |
文档不被允许使用 window-management Permissions Policy 特性(默认允许列表为 'self');或权限没有被授予:用户拒绝或关闭了提示,或调用时没有瞬时激活而权限仍是 "prompt"(Chromium 此时不发起请求,直接拒绝)。窗口显示状态方法在文档不是已安装 Web 应用、缺少瞬时激活或操作系统拒绝更改时也以它拒绝。 |
isExtended 不抛任何异常,Permissions Policy 拦截该特性时返回 false,所以 false 的含义是「单屏,或不被允许知道」。FullscreenOptions.screen 只是应用的偏好,浏览器可以让用户的选择优先;规范没有为它定义拒绝情形。
将单屏操作用作回退方案。Firefox 和 Safari 会跳过多屏分支。用户拒绝权限时 getScreenDetails() 会拒绝,只有第一个示例用 catch 接住并回退,后两个示例需要自己加这层处理。
在副屏上打开伴随窗口
链接到“在副屏上打开伴随窗口”一节先检查 isExtended,这一步不弹提示。再在 click 处理器内调用 getScreenDetails(),让浏览器可以请求权限。调用失败时回退到普通的 window.open()。
button.addEventListener("click", async () => { const url = "/presenter-notes"; if (!("getScreenDetails" in window) || !window.screen.isExtended) { window.open(url, "_blank", "popup"); return; } try { const details = await window.getScreenDetails(); const target = details.screens.find((s) => s !== details.currentScreen) ?? details.currentScreen; const features = `popup,left=${target.availLeft},top=${target.availTop},width=${target.availWidth},height=${target.availHeight}`; window.open(url, "_blank", features); } catch (err) { console.warn(`${err.name}: ${err.message}`); window.open(url, "_blank", "popup"); }});权限授予后,features 字符串里的 left 和 top 按多屏原点解释,所以位于主屏左侧或上方的显示器用负坐标是合法的。
在外接显示器上全屏演示,笔记留在笔记本屏幕
链接到“在外接显示器上全屏演示,笔记留在笔记本屏幕”一节把选中的 ScreenDetailed 传给 FullscreenOptions.screen。按规范,跨屏全屏请求成功后,紧接着的一次 window.open() 可以免去激活要求,因此同一次点击也能打开笔记窗口。
async function startPresentation(slides) { if (!("getScreenDetails" in window)) { return slides.requestFullscreen(); // 仅当前屏幕 } const details = await window.getScreenDetails(); const external = details.screens.find((s) => !s.isInternal); if (!external) return slides.requestFullscreen();
await slides.requestFullscreen({ screen: external }); const notes = details.screens.find((s) => s.isInternal) ?? details.currentScreen; window.open("/notes", "_blank", `popup,left=${notes.availLeft},top=${notes.availTop},width=800,height=600`);}如果屏幕都报告 isInternal: false,例如接两台显示器的台式机,代码会把笔记放在当前屏幕上。
响应显示器的插入与移除
链接到“响应显示器的插入与移除”一节在 ScreenDetails 对象上监听 screenschange,window 不会收到这个事件。屏幕变化后,新的 screens 数组会替换原数组,原数组保持不变。在处理器中重新读取数组,并关闭已移除屏幕上的伴随窗口。
async function watchScreens(onChange) { if (!("getScreenDetails" in window)) { window.screen.addEventListener("change", () => onChange([window.screen])); return; } const details = await window.getScreenDetails(); onChange(details.screens); details.addEventListener("screenschange", () => onChange(details.screens)); details.addEventListener("currentscreenchange", () => { document.documentElement.style.setProperty("--dpr", details.currentScreen.devicePixelRatio); });}单屏回退监听的是同一份规范为 Screen 新增的 change 事件,窗口当前屏幕的基本属性(尺寸、可用尺寸、色深、方向)变化时触发。像素比属于高级属性,它的变化会触发 ScreenDetailed.change 和 currentscreenchange,不会触发 Screen.change。
另请参阅
链接到“另请参阅”一节- display_override,决定已安装窗口可用哪些显示模式的 manifest 成员
- Tabbed application mode 与 tab_strip
- 桌面端的 PWA
- Window Management: getScreenDetails() method(w3.org)
- Window Management: permission API integration(w3.org)
- Manage several displays with the Window Management API(developer.chrome.com)
- Chromium: window_screen_details.cc(chromium.googlesource.com)
规范
| 规范 | 状态 |
|---|---|
| Window Management(窗口管理) | W3C 草案 |
| Window Management: getScreenDetails() method | W3C 草案 |
| Window Management: ScreenDetailed interface | W3C 草案 |
| Window Management: extensions to FullscreenOptions | W3C 草案 |
- 图例
- 支持
- 部分支持
- 需开启标志
- 不支持
- 未知
| 浏览器 / 平台 | 支持 | 版本 | 置信度 | 来源 | 备注 |
|---|---|---|---|---|---|
| Chrome (Desktop)# | 支持 | 100 | 高 | 来源 | — |
| Chrome (Android)# | 支持 | 100 | 高 | 来源 | 1 |
| Edge (Desktop)# | 支持 | 100 | 高 | 来源 | 2 |
| Firefox (Desktop)# | 不支持 | — | 高 | 来源 | 3 |
| Firefox (Android)# | 不支持 | — | 高 | 来源 | 45 |
| Safari (macOS)# | 不支持 | — | 高 | 来源 | 6 |
| Safari (iOS)# | 不支持 | — | 高 | 来源 | 78 |
| Samsung Internet# | 支持 | 19.0 | 高 | 来源 | 9 |
| WebView (Android)# | 支持 | 100 | 高 | 来源 | 10 |
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- 由 browser-compat-data 镜像自 Chrome 的数据推导。
- browser-compat-data 未记录 Firefox 的支持。
- browser-compat-data 未记录 Firefox for Android 的支持。
- 由 browser-compat-data 镜像自 Firefox 的数据推导。
- browser-compat-data 未记录 Safari 的支持。
- browser-compat-data 未记录 iOS 版 Safari 的支持。
- 由 browser-compat-data 镜像自 Safari 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
- 由 browser-compat-data 镜像自 Chrome Android 的数据推导。