Window Controls Overlay（WCO）通过将系统窗口控件以覆盖层形式浮于网页内容之上，释放顶部区域供自由布局；需在 manifest.json 中配置 display_override:["window-controls-overlay"] 且 display 为 standalone 或 minimal-ui，并利用 env() 变量适配多平台标题栏差异及动态开关状态。
直接把内容延伸到标题栏区域，是优化桌面 PWA 布局空间最有效的方式。Window Controls Overlay（WCO）不是隐藏标题栏，而是将系统窗口控件（最小化、最大化、关闭按钮）以覆盖层形式浮在网页内容之上，同时把原本被标题栏“占用”的顶部区域释放出来，供你自由排布 UI 元素。
启用 WCO 需要清单文件配置
核心前提是你的 PWA 已声明支持该能力。在 web app manifest（如 manifest.json）中，必须设置 display_override 字段：
- 添加
"window-controls-overlay"到display_override数组中，例如：{"display_override": ["window-controls-overlay"]} - 确保
display字段仍为"standalone"或"minimal-ui"，否则 WCO 不生效 - 清单文件需通过
<link rel="manifest">正确关联到 HTML 中
用 CSS 环境变量定位标题栏可用区域
启用后，浏览器会注入四个 env() CSS 环境变量，精确描述系统控件所占区域的位置与尺寸：
-
env(titlebar-area-x)（x 可为left、top、width、height） - 例如：
padding-top: env(titlebar-area-height, 32px);—— 让主内容避开控件区，同时提供回退值 - 这些变量只在 WCO 激活时有值；未激活时（如在浏览器标签页中运行），会使用你指定的 fallback 值
适配不同平台的视觉差异
Windows、macOS 和 Linux 的标题栏高度、按钮位置、阴影风格各不相同。不能靠固定像素值硬写：
- 在 DevTools 的 Application → Manifest → Window Controls Overlay 中，可分别模拟三类平台，实时查看变量取值变化
- 推荐用
env(titlebar-area-height)控制顶部留白，而非写死40px或36px - macOS 下关闭按钮在左侧，Windows/Linux 在右侧，自定义标题栏内容需注意对齐逻辑是否兼容
响应式处理标题栏开关状态
用户可在系统级手动开启或关闭标题栏显示（比如右键点击标题栏选择“显示标题栏”），你的界面必须能动态适应：
- 监听
geometrychange事件：window.addEventListener('geometrychange', () => { /* 更新布局 */ }) - 避免假设 WCO 总是启用——PWA 可能在浏览器中打开、在移动设备上运行，或用户禁用了标题栏
- 用
@supports (env(titlebar-area-height))做 CSS 特性检测，渐进增强样式
