如何在HTML中通过Window Controls Overlay自定义PWA标题栏区域-html教程-PHP中文网

必须在 manifest.json 中配置 display_override:["window-controls-overlay"] 才能启用窗口控件覆盖功能，仅对已安装的桌面 pwa 有效；需用 window.windowcontrolsoverlay.getboundingclientrect() 动态获取标题栏高度并监听 geometrychange 事件；css 中使用 titlebar-area 和 -webkit-app-region 控制拖动与避让。

如何在html中通过window controls overlay自定义pwa标题栏区域

必须先在 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) // 实际可用的标题栏区域高度
}

注意点：

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 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;
}

说明：