20. 窗口配置与样式

本节目标

• 知道窗口的外观参数是在 wails.Run 之前写好的。
• 会用 Width、Height、Min/Max 系列控制窗口尺寸范围。
• 理解启动状态、隐藏关闭、背景色与拖拽属性的写法。

20-1 配置写在哪

窗口的长相不是运行时改的，是在启动前定下来的。

所有配置都塞进 options.App 这个结构体，再传给 wails.Run：

func main() {
    err := wails.Run(&options.App{
        Title:  "码上学笔记",
        Width:  1024,
        Height: 768,
        // 更多字段往下加
    })
    if err != nil {
        log.Fatal(err)
    }
}

本章只讲和窗口外观直接相关的字段。菜单、托盘、拖放那些，后面有专门的章节。

20-2 尺寸与缩放限制

Width 和 Height 决定窗口刚弹出时的大小。

想禁止用户拉大拉小，设 DisableResize 为 true：

DisableResize: true,

更常见的做法是给一个范围。最小宽高、最大宽高都能单独设：

MinWidth:  400,
MinHeight: 300,
MaxWidth:  1280,
MaxHeight: 800,

这几个字段是”启动前写死”的。想运行时再改，去上一章看 WindowSetSize 和 WindowSetMinSize。

20-3 启动状态与显隐

窗口一打开是什么样子，用 WindowStartState 控制。

它有三个可选值：options.Maximised、options.Minimised、options.Fullscreen。

WindowStartState: options.Maximised,

StartHidden 让窗口启动后先藏起来，等你主动 WindowShow 才露面：

StartHidden: true,

HideWindowOnClose 是个很实用的开关。默认点右上角关闭，整个程序就退出了。设成 true，点关闭只是把窗口藏起来，程序还在后台跑：

HideWindowOnClose: true,

20-4 背景色与置顶

窗口默认背景是白色。想换底色，用 BackgroundColour，类型是 *options.RGBA：

BackgroundColour: &options.RGBA{R: 0, G: 0, B: 0, A: 255},

也可以用现成的构造函數。要半透明就调 NewRGBA，不透明用 NewRGB：

BackgroundColour: options.NewRGBA(255, 0, 0, 128), // 半透明红

让窗口永远盖在最上面，设 AlwaysOnTop：

AlwaysOnTop: true,

适合做录屏工具、计时器这种”一直要看着”的小窗。

20-5 拖拽属性与文件拖放

无边框窗口怎么拖动？Wails 靠一个 CSS 属性来认拖拽区。

相关配置叫 CSSDragProperty 和 CSSDragValue，默认值分别是 --wails-draggable 和 drag。

CSSDragProperty: "--wails-draggable",
CSSDragValue:    "drag",

也就是说，前端哪个元素写了 --wails-draggable: drag，哪里就能拖窗口。下一章会细讲。

文件拖放也有一组开关，统一放在 DragAndDrop 里：

DragAndDrop: &options.DragAndDrop{
    EnableFileDrop:     true,  // 开启拖文件进窗口
    DisableWebViewDrop: false, // 关掉网页原生拖放
    CSSDropProperty:    "--wails-drop-target",
    CSSDropValue:       "drop",
},

EnableFileDrop 打开后，拖进来的文件路径才能被运行时拿到。具体怎么用，第 25 章专门讲。

20-6 实战：启动即最大化且固定

来个小实战。做一个笔记工具的窗口：启动就最大化，禁止用户改大小，最小宽高兜个底，关窗口不退出（留给托盘）。

err := wails.Run(&options.App{
    Title:             "码上学笔记",
    Width:             1024,
    Height:            768,
    DisableResize:     true,
    MinWidth:          800,
    MinHeight:         600,
    WindowStartState:  options.Maximised,
    HideWindowOnClose: true,
    // 下面接 AssetServer、Bind 等
})

这段配置几乎覆盖了本章所有字段。DisableResize 和 MinWidth 同时写并不冲突，前者锁死大小，后者只是兜底下限。

20-7 配置字段速查

把本章字段收一张表，免得来回翻：

字段	作用	默认
Width / Height	初始大小	1024 / 768
DisableResize	禁止缩放	false
MinWidth / MinHeight	最小尺寸	0
MaxWidth / MaxHeight	最大尺寸	0
WindowStartState	启动状态	Normal
StartHidden	启动隐藏	false
HideWindowOnClose	关窗不退出	false
BackgroundColour	背景色	白
AlwaysOnTop	置顶	false
Frameless	无边框	false

这些都在 wails.Run 之前写好。启动后想改，基本都有对应的 runtime 方法，去第 19 章找。

20-8 透明与毛玻璃前瞻

顺带提一个和窗口样式强相关的话题：透明与毛玻璃。

Wails 在 Windows 上支持把 webview 和窗口做成半透明。关键是两个开关：WebviewIsTransparent 和 WindowIsTranslucent，都写在 Windows 子选项里。

Windows: &windows.Options{
    WebviewIsTransparent: true,
    WindowIsTranslucent:  true,
    BackdropType:         windows.Mica,
},

透明生效的前提是 CSS 背景用 rgba(0,0,0,0)，这样宿主窗口才会透出来。再配合本章的 BackgroundColour，就能做出磨砂质感的界面。

20-9 排错清单

配置类问题，几个高频坑。

第一，Fullscreen: true 编译告警或报错。那是废弃字段，改用 WindowStartState: options.Fullscreen。

第二，填了 Width 却被撑到 MinWidth。这是正常行为，Wails 会保证窗口不小于下限，不用自己写判断。

第三，背景色不生效。确认你用的是 *options.RGBA 指针，且 Alpha 通道设置正确。想要透明，还得配合 Windows 的 WebviewIsTransparent。

第四，改了配置没反应。配置是启动前生效的，程序跑起来再改字段没用，要用第 19 章的 runtime 方法。

常见误区