Wails v3 跨平台窗口:菜单、主题与无边框命中测试
同一个 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 | 系统 | 重建主窗口,沿用位置、尺寸和最大化状态 |
| Linux | GTK | 用 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 与桌面工程记录在 后端开发。
評論
還沒有評論,來說兩句吧