Wails v3 跨平台窗口:菜单、主题与无边框命中测试

2026-11-19 后端开发 有希 49 次瀏覽

同一个 Wails 窗口,Windows 上菜单栏不出现、macOS 切主题后标题栏仍是旧色、Linux 菜单不跟色,最大化后边缘还会冒出缩放光标。这些问题看起来分散,根因却集中在一个事实:窗口的一部分由 WebView 绘制,另一部分由操作系统绘制。

菜单:先建菜单,再建窗口

先说结论:Windows 和 Linux 的应用菜单是在窗口创建时挂上去的,菜单必须比主窗口先存在。

这个项目曾经出现过“菜单已经建好,界面上一条都没有”的情况,三处顺序各错一点:

  • 创建窗口时没有声明使用应用菜单。
  • 建菜单的代码排在创建窗口之后。
  • 切换语言重建菜单后,没有把新菜单重新挂到已经建好的窗口上。
// 先建菜单,再建窗口
a.setupMenu()
a.MainWindow = newMainWindow(wailsApp, cfg, a.mainURL(), placement)

// 语言切换后重建菜单:全局设置之后,还要给已有窗口补一次
application.SetApplicationMenu(menu)
a.MainWindow.SetMenu(menu)

只调用 SetApplicationMenu 不够。它更新的是全局指针,已经创建好的窗口不会自动补挂;而重建菜单又销毁了旧菜单项,于是窗口上可能留下一条空菜单栏。

平台菜单归属重建菜单后的处理
Windows窗口级原生菜单栏全局设置后对主窗口 SetMenu
Linux窗口级,由 GTK 绘制同 Windows,并同步 GTK 配色
macOS应用级全局菜单设置全局菜单即可,不需要逐窗口挂

前端自绘菜单时还要注意另一条边界:原生菜单和前端菜单不要同时启用。Windows 上如果窗口改成无边框、菜单由前端绘制,原生菜单就应该关掉,否则两套菜单会抢同一块区域。

子窗口:关闭即销毁,不要藏

Wails 的窗口被关闭后会从管理器移除。Show() 依赖 Run() 重建,而 Run() 在内部实现仍非空时直接返回——已经销毁的实例唤不回来。表现就是:第一次打开子窗口正常,关掉之后再点“打开”没有任何反应,因为代码还在对一个死对象调用 Show()。

修法不是“关闭即隐藏”,而是在关闭时清空引用,下次重新创建:

win.RegisterHook(events.Common.WindowClosing, func(*application.WindowEvent) {
    a.childWindow = nil
})

// 下次打开时
if a.childWindow == nil {
    a.childWindow = createChildWindow()
}
a.childWindow.Show().Focus()

为什么不能靠隐藏保住实例?Windows 上要等原生窗口全部注销,主窗口关闭才会退出进程。一个被隐藏的子窗口会让进程在没有界面、也没有托盘的情况下继续存活。用户看到的是“软件关了,但任务管理器里还在;再双击图标也打不开”。

窗口对象的生命周期跟着原生窗口走,不要把它当成普通结构体缓存。

主题:Wails 只在建窗时应用

Wails v3 没有运行时的 SetTheme 接口,主题只在创建窗口时应用。不同平台的原生部分不同,处理方式也不能一刀切:

平台谁绘制标题栏/菜单栏切换主题的策略
Windows(自绘 chrome)前端只改 CSS,不重建窗口
macOS系统重建主窗口,沿用位置、尺寸和最大化状态
LinuxGTK用 GTK 设置改菜单配色,不重建窗口

macOS 重建窗口是唯一能让原生外观和界面同时生效、又不依赖未公开 AppKit 调用的做法。重建时先换掉 a.MainWindow 引用,再关闭旧窗口,这样旧窗口的关闭钩子会直接放行,不会把已经隐藏的旧窗口再隐藏一次。

Linux 不重建,因为重建窗口不会让 GTK 主题跟着变,只会把整个 WebView 重载一遍。菜单栏是 GTK 控件,只能用 GTK 设置改配色。

首帧不要闪白

主题还存在一个首帧问题:模块加载完成前,页面已经显示了一瞬间的默认背景。桌面应用表现为启动时闪一下白屏,暗色主题下尤其明显。

这里在 index.html 里放一段模块加载前执行的脚本,直接读窗口地址上的 ?theme=:

<script>
  ;(() => {
    const mode = new URLSearchParams(location.search).get('theme')
    const dark =
      mode === 'dark' ||
      (mode === 'system' &&
        matchMedia('(prefers-color-scheme: dark)').matches)
    document.documentElement.classList.add(dark ? 'dark' : 'light')
    document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
  })()
</script>

Go 侧建窗时把主题写进 URL,前端首帧就能采用同一套明暗,不必等异步调用返回。想快速确认当前 WebView 的版本标识,可以用 User-Agent 解析 对照。这里还有一个语义区分:启动时回报的主题只是“系统当前的样子”,不是用户选择;只有用户明确切换才写进配置。否则 system 模式会被首帧固化成 light 或 dark。

这类首帧不一致和浏览器里的 SSR 水合问题很像,都是“服务端/宿主已经画了一版,客户端又画了另一版”。区别只是这里的第一版由原生窗口画。相关思路可以看 Nuxt 首帧不一致。

无边框最大化:命中测试要自己接管

Windows 上把窗口改成无边框后,窗口仍然保留 WS_THICKFRAME,否则就彻底失去缩放能力。问题出在最大化状态:窗口矩形会超出工作区一圈边框宽度,而 WebView2 把客户区四周当作可缩放边框,在边缘约 8px 的热区里上报缩放光标。

最大化时这些热区正好压在屏幕和工作区的边上,顶部那半个上下箭头还会伸出屏幕。用户看到的是:窗口已经最大化,鼠标移到边缘却变成缩放箭头,点了也没反应。

修法是对窗口做子类化,在最大化期间接管命中测试:

case wmNCHitTest:
    if isMaximised(hwnd) {
        return htClient
    }

case wmSetCursor:
    if lparam&0xffff != htClient && isMaximised(hwnd) {
        procSetCursor.Call(arrowCursor)
        return 1
    }

HTCLIENT 表示把这块区域交回客户区处理;还原窗口后不再拦截,真实边框的缩放光标保持原样。不要图省事全局禁用缩放,否则窗口还原后也没法拖边。

光标还有异步问题:WebView2 设置光标是异步回调,最后一次设置可能发生在鼠标消息处理完之后。所以除了在 WM_SETCURSOR 里当场纠正,还要用一个 50ms 的定时器定期兜底,专门处理“鼠标已经离开边缘,光标还停在缩放形状”的残留。

场景期望处理
最大化 + 客户区边缘普通箭头WM_NCHITTEST 返回 HTCLIENT
最大化 + 系统非客户区命中普通箭头WM_SETCURSOR 改回箭头
还原后的真实边框缩放光标不拦截,交给系统
光标异步残留尽快恢复50ms 定时器兜底

窗口状态:防抖写盘,但退出要补写

窗口位置和尺寸的保存有两个极端:每次移动都写盘,拖动一次会产生几十次 I/O;只在退出时写,崩溃或强杀就丢了。

这里的折中是移动和缩放走 700ms 防抖,最大化、还原、关闭立即写盘。退出路径还要再补一次,因为托盘退出和菜单退出不经过窗口关闭事件,防抖计时器可能还挂着。

const (
    saveDelay      = 700 * time.Millisecond
    minVisibleEdge = 80
)

保存最大化状态时要特别小心:最大化后的 Bounds() 是铺满屏幕的矩形,不能当成“普通尺寸”存下来,否则下次还原时窗口会变成全屏大小。正确做法是只更新 Maximised 标志,位置和尺寸沿用之前记录的普通状态。

另一个容易忽略的场景是显示器变化。用户拔掉副屏、改了分辨率,或者把笔记本从扩展屏带回主屏,旧坐标可能完全落在屏幕外。这里的判断标准不是“窗口是否可见”,而是“是否至少有 80×80 的区域落在某块屏幕的工作区内”。不满足就把窗口移到主屏中央,尺寸超出工作区的部分裁掉。

窗口状态是用户数据,不是缓存。 读不出来可以回退默认值,但不要因为一次异常坐标就把用户的布局清空。

打包阶段还有一组平台坑

窗口代码跑通,不代表安装包能装。这个项目在打包阶段踩过的坑更杂:

现象根因处理
pnpm install 不报错,但依赖其实没装上受限环境禁止创建符号链接设置 node-linker=hoisted
go:embed frontend/dist 构建失败空目录不会被 git 跟踪,embed 找不到文件先构建前端,保留占位文件
重新生成构建资产后名称、版权、版本全回退手工改过生成文件,唯一来源仍是构建配置只改配置,重新生成
NSIS 报 Bad text encoding.nsi 没有 BOM,非 ASCII 注释按系统代码页读取脚本保持纯 ASCII,中文说明放外部
arm64 安装包里塞了 amd64 的更新助手打包任务没有设置 GOOS/GOARCH显式按目标平台构建
Linux/macOS 包里出现 .exe 后缀生成资产沿用了 Windows 名字按平台重新生成并检查 CFBundleExecutable
开发版被正式版单实例锁接管两者使用同一个锁 ID开发构建使用带 -dev 后缀的 ID

这些问题的共同点是:它们都不在业务代码里,但都会让“构建成功”变成“装上不能用”。 发布前至少要在目标平台上跑一遍安装、启动、更新和卸载,不能只看 CI 绿了没有。版本注入和更新信任链的完整设计,见 Wails 分层与更新信任链。

FAQ

为什么菜单建好了,窗口上却看不到?

Windows 和 Linux 的菜单在窗口创建时挂载。检查三件事:创建窗口时是否声明使用应用菜单、菜单是否先于窗口创建、重建菜单后是否对已有窗口重新 SetMenu。

子窗口关闭后为什么再也打不开?

Wails 关闭窗口后会移除实例,已销毁的窗口不能靠 Show() 复活。需要在关闭事件里清空引用,下次重新创建。不要改成隐藏,隐藏的子窗口会阻止进程退出。

主题切换为什么在 macOS 上要重建窗口?

Wails v3 只会在建窗时应用原生外观,没有运行时 SetTheme。macOS 的原生标题栏必须重建窗口才能换色;Windows 自绘 chrome 和 Linux GTK 菜单各有更轻的同步方式。

最大化时为什么鼠标会变成缩放箭头?

无边框窗口仍保留缩放边框,WebView2 把客户区边缘当成了可缩放热区。最大化时这些热区正好压在屏幕边缘。需要在最大化期间把命中测试固定为客户区,并在光标消息里纠正。

保存的窗口位置跑到屏幕外怎么办?

窗口就绪后重新校验它是否至少有 80×80 的区域落在某块屏幕的工作区内。不满足就移到主屏中央。不要只判断坐标是否在某个范围内,显示器布局变化后旧坐标可能仍然“合法”但不可操作。

结语

Wails 的跨平台窗口不是“写一次,三端自动一致”。菜单、主题、窗口边框和光标,每一项都要先判断这块区域由谁绘制,再决定是交给系统、交给 WebView,还是自己接管。把这条边界想清楚,平台差异就从玄学变成了可验证的分支。正在做框架选型的话,可以对照 桌面框架选型对比;更多 Go 与桌面工程记录在 后端开发。

評論

登入後即可參與評論

還沒有評論,來說兩句吧

相關文章