必须在 manifest.json 中配置 display_override:["window-controls-overlay"] 才能启用窗口控件覆盖功能，仅对已安装的桌面 PWA 有效；需用 window.windowControlsOverlay.getBoundingClientRect() 动态获取标题栏高度并监听 geometrychange 事件；CSS 中使用 titlebar-area 和 -webkit-app-region 控制拖动与避让。
必须先在 manifest.json 中启用 window-controls-overlay
不配置 manifest，后续所有 JS 和 CSS 都不会生效。这是整个功能的开关，且只对已安装的桌面 PWA 有效（网页内直接打开无效）。
在你的 manifest.json 文件中，display_override 字段必须显式包含 "window-controls-overlay"，且不能被其他 display 值覆盖：
{
"display": "standalone",
"display_override": ["window-controls-overlay"],
"name": "My App",
"short_name": "App"
}
常见错误：
-
display_override拼错成displayOverride或漏掉下划线 - 把
"window-controls-overlay"写成"window-control-overlay"（少一个s） - 同时设了
"display": "minimal-ui"—— 这会覆盖display_override，导致 API 不激活
用 getBoundingClientRect() 获取标题栏区域尺寸
系统保留的标题栏高度不是固定的，不同平台、DPI、系统缩放比例下都不同。不能写死 top: 32px 这类值。
立即学习“前端免费学习笔记（深入）”；
必须通过 window.windowControlsOverlay API 动态读取：
if ('windowControlsOverlay' in window) {
const bounds = window.windowControlsOverlay.getBoundingClientRect()
console.log(bounds.height) // 实际可用的标题栏区域高度
}
注意点：
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 该 API 只在已启用
window-controls-overlay且当前运行于桌面 PWA 环境时存在 - 用户手动隐藏标题栏（点击右上角标题栏切换按钮）会导致
bounds.height === 0，代码需兼容此情况 - 监听
windowControlsOverlay.geometrychange事件，响应 DPI 切换或窗口缩放变化
用 titlebar-area CSS 属性控制内容定位
原生窗口控件（关闭/最小化按钮）会自动叠加在顶部，你的 HTML 元素需要避开它们，或主动对齐到控件右侧。
关键 CSS 属性是 titlebar-area，它只在 window-controls-overlay 启用时生效：
.titlebar {
-webkit-app-region: drag;
padding: 0 12px;
height: 100%;
display: flex;
align-items: center;
}
.titlebar > .controls {
-webkit-app-region: no-drag;
margin-left: auto;
}
说明：
-
-webkit-app-region: drag让元素可拖动整个窗口，但必须加在容器上，不能加在按钮本身 -
-webkit-app-region: no-drag必须加在按钮等交互控件上，否则点不到 - 不要用
position: absolute; top: 0强行贴顶 —— 它会遮挡系统按钮，且在高 DPI 下错位
Electron 用户别混淆：这不是 Electron 的 titleBarStyle
Window Controls Overlay 是纯 Web 标准（Chromium/Edge 111+、Firefox 126+ 支持），和 Electron 的 titleBarStyle: 'hidden' 或 titleBarOverlay: true 完全无关。
如果你在 Electron 里想实现类似效果，要走另一套路径：
- 设置
titleBarStyle: 'hidden'+titleBarOverlay: true - 在渲染进程里调用
remote.getCurrentWindow().setTitleBarOverlay({ color: '#fff' }) - 然后用 CSS 覆盖
body顶部区域，并手动处理拖动逻辑
Web PWA 和 Electron 是两套独立机制，混用会导致标题栏空白、按钮不可点、拖动失效等静默失败。
