跳转到内容

能力中的 API

Window Management API

发布于 更新于

有限可用不支持的浏览器: Firefox (Desktop)、Firefox (Android)、Safari (macOS)、Safari (iOS)W3C 草案

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.screens
screenDetails.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。

规范

规范状态
Window Management(窗口管理)W3C 草案
Window Management: getScreenDetails() methodW3C 草案
Window Management: ScreenDetailed interfaceW3C 草案
Window Management: extensions to FullscreenOptionsW3C 草案
  • 图例
  • 支持
  • 部分支持
  • 需开启标志
  • 不支持
  • 未知
浏览器 / 平台支持版本置信度来源备注
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
  1. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  2. 由 browser-compat-data 镜像自 Chrome 的数据推导。
  3. browser-compat-data 未记录 Firefox 的支持。
  4. browser-compat-data 未记录 Firefox for Android 的支持。
  5. 由 browser-compat-data 镜像自 Firefox 的数据推导。
  6. browser-compat-data 未记录 Safari 的支持。
  7. browser-compat-data 未记录 iOS 版 Safari 的支持。
  8. 由 browser-compat-data 镜像自 Safari 的数据推导。
  9. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。
  10. 由 browser-compat-data 镜像自 Chrome Android 的数据推导。

源数据: /compatibility/window-management.json · 全球使用占比: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

来源: 规范 · MDN · 最近核验 2026-10-03 · 置信度: 高 (由来源计算)