OpenPWAStore
返回 News
Guide · May 20, 2026

Window Controls Overlay 让桌面 PWA 拥有真正的原生窗口体验

桌面 PWA 现在可以与原生窗口控件深度集成，获得无缝的操作系统体验。

OpenPWA Editorial1 min read
中文English
Window Controls Overlay 让桌面 PWA 拥有真正的原生窗口体验 cover

为什么桌面 PWA 需要这个能力

大多数桌面 PWA 仍然看起来像带细标题栏的浏览器窗口。Window Controls Overlay API 的出现改变了这一点，它允许你的应用绘制到整个标题栏区域，同时操作系统保留最小化、最大化和关闭按钮。

这很重要，因为用户期望已安装的应用感觉像原生应用。尊重桌面环境的 PWA 会立即建立信任，减少"这只是个网站"的感知。

如何实现 Window Controls Overlay

在 web app manifest 中添加 display-override 字段：

{
  "display_override": ["window-controls-overlay"]
}

然后在 JavaScript 中使用 Window Controls Overlay API：

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', (e) => {
    const { titlebarAreaRect } = e;
    // 在 titlebarAreaRect 范围内定位自定义标题栏内容
  });
}

生产级桌面 PWA 检查清单

  • [ ] 在 manifest 中设置 display_override 包含 "window-controls-overlay"
  • [ ] 在 Windows、macOS 和 Linux（基于 Chromium）上测试
  • [ ] 通过 CSS color-scheme 尊重系统主题的标题栏颜色
  • [ ] 为不支持该 API 的浏览器提供回退方案
  • [ ] 确保可拖动区域与 -webkit-app-region: drag 正确配合
  • [ ] 保持关闭/最小化按钮可访问且位置正确

参考来源