跳到主要内容
版本:下个版本 🚧

参数选项

应用程序参数选项​

该 Options.App 结构包含应用程序配置。 它被传递给 wails.Run() 方法:

Example
import (
"github.com/wailsapp/wails/v2/pkg/options"
"github.com/wailsapp/wails/v2/pkg/options/assetserver"
"github.com/wailsapp/wails/v2/pkg/options/linux"
"github.com/wailsapp/wails/v2/pkg/options/mac"
"github.com/wailsapp/wails/v2/pkg/options/windows"
)

func main() {

err := wails.Run(&options.App{
Title: "Menus Demo",
Width: 800,
Height: 600,
DisableResize: false,
Fullscreen: false,
WindowStartState: options.Maximised,
Frameless: true,
MinWidth: 400,
MinHeight: 400,
MaxWidth: 1280,
MaxHeight: 1024,
StartHidden: false,
HideWindowOnClose: false,
BackgroundColour: &options.RGBA{R: 0, G: 0, B: 0, A: 255},
AlwaysOnTop: false,
AssetServer: &assetserver.Options{
Assets: assets,
Handler: assetsHandler,
Middleware: assetsMidldeware,
},
Menu: app.applicationMenu(),
Logger: nil,
LogLevel: logger.DEBUG,
LogLevelProduction: logger.ERROR,
OnStartup: app.startup,
OnDomReady: app.domready,
OnShutdown: app.shutdown,
OnBeforeClose: app.beforeClose,
CSSDragProperty: "--wails-draggable",
CSSDragValue: "drag",
EnableFraudulentWebsiteDetection: false,
ZoomFactor: 1.0,
IsZoomControlEnabled: false,
Bind: []interface{}{
app,
},
Windows: &windows.Options{
WebviewIsTransparent: false,
WindowIsTranslucent: false,
BackdropType: windows.Mica,
DisableWindowIcon: false,
DisableFramelessWindowDecorations: false,
WebviewUserDataPath: "",
WebviewBrowserPath: "",
Theme: windows.SystemDefault,
CustomTheme: &windows.ThemeSettings{
DarkModeTitleBar: windows.RGB(20, 20, 20),
DarkModeTitleText: windows.RGB(200, 200, 200),
DarkModeBorder: windows.RGB(20, 0, 20),
LightModeTitleBar: windows.RGB(200, 200, 200),
LightModeTitleText: windows.RGB(20, 20, 20),
LightModeBorder: windows.RGB(200, 200, 200),
},
// User messages that can be customised
Messages *windows.Messages
// OnSuspend is called when Windows enters low power mode
OnSuspend func()
// OnResume is called when Windows resumes from low power mode
OnResume func(),
WebviewGpuDisabled: false,
},
Mac: &mac.Options{
TitleBar: &mac.TitleBar{
TitlebarAppearsTransparent: true,
HideTitle: false,
HideTitleBar: false,
FullSizeContent: false,
UseToolbar: false,
HideToolbarSeparator: true,
},
Appearance: mac.NSAppearanceNameDarkAqua,
WebviewIsTransparent: true,
WindowIsTranslucent: false,
About: &mac.AboutInfo{
Title: "My Application",
Message: "© 2021 Me",
Icon: icon,
},
},
Linux: &linux.Options{
Icon: icon,
WindowIsTranslucent: false,
WebviewGpuPolicy: linux.WebviewGpuPolicyAlways,
},
Debug: options.Debug{
OpenInspectorOnStartup: false,
},
})

if err != nil {
log.Fatal(err)
}
}

标题​

窗口标题栏中显示的文本。

名称:Title
类型:string

宽度​

窗口的初始宽度。

名称:Width
类型:int
默认值:1024.

高度​

窗口的初始高度。

名称:Height
类型:int
默认值:768

禁用调整窗口尺寸​

默认情况下,主窗口可调整大小。 将此设置为 true 将使其保持固定大小。

名称:DisableResize
类型:bool

全屏​

已弃用:请使用 窗口启动状态.

窗口启动状态​

定义窗口在启动时应如何呈现。

值WinMacLin
Fullscreen(全屏)✅✅✅
Maximised(最大化)✅✅✅
Minimised(最小化)✅❌✅

名称:WindowStartState
类型:options.WindowStartState

无边框​

设置为true时,窗口将没有边框或标题栏。 另请参阅 无边框窗口。

名称:Frameless
类型:bool

最小宽度​

这将设置窗口的最小宽度。 如果给出的值 Width 小于这个值,窗口将被设置为 MinWidth 默认值。

名称:MinWidth
类型:int

最小高度​

这将设置窗口的最小高度。 如果给出的值 Height 小于这个值,窗口将被设置为 MinHeight 默认值。

名称:MinHeight
类型:int

最大宽度​

这将设置窗口的最大宽度。 如果给出的值 Width 大于这个值,窗口将被设置为 MaxWidth 默认值。

名称:MaxWidth
类型:int

最大高度​

这将设置窗口的最大高度。 如果给出的值 Height 大于这个值,窗口将被设置为 MaxHeight 默认值。

名称:MaxHeight
类型:int

启动时隐藏窗口​

设置为 true 时,应用程序将被隐藏,直到调用 显示窗口。

名称:StartHidden
类型:bool

关闭时隐藏窗口​

默认情况下,关闭窗口将关闭应用程序。 将此设置为 true 意味着关闭窗口将隐藏窗口。

隐藏窗口。

名称:HideWindowOnClose
类型:bool

背景颜色​

此值是窗口的默认背景颜色。 示例:options.NewRGBA(255,0,0,128) - 红色,透明度为 50%

名称:BackgroundColour
类型:*options.RGBA
默认值:white

窗口固定在最顶层​

窗口在失去焦点时应保持在其他窗口之上。

名称:AlwaysOnTop
类型:bool

资产​

已弃用:请在 AssetServer 特定选项 上使用资产。

资产处理程序​

已弃用:请在 AssetServer 特定选项 上使用资产处理程序。

资产服务器​

这定义了资产服务器特定的选项。 它允许使用静态资产自定义资产服务器,使用 http.Handler 动态地提供资产或使用 assetsserver.Middleware 钩到请求链。

并非当前支持 http.Request 的所有功能,请参阅以下功能矩阵:

功能WinMacLin
GET✅✅✅
POST✅✅✅ 1
PUT✅✅✅ 1
PATCH✅✅✅ 1
DELETE✅✅✅ 1
Request Headers✅✅✅ 1
Request Body✅✅✅ 2
Request Body Streaming✅✅✅ 2
Response StatusCodes✅✅✅ 1
Response Headers✅✅✅ 1
Response Body✅✅✅
Response Body Streaming❌✅✅
WebSockets❌❌❌
HTTP Redirects 30x✅❌❌

名称: AssetServer
类型: *assetserver.Options

资产​

应用程序要使用的静态前端资产。

首先尝试从 fs.FS 提供 GET 请求。 如果 fs.FS 为该文件返回 os.ErrNotExist,则请求处理将回退到 处理程序 并尝试服务来自它的 GET 请求。

如果设置为 nil,则所有 GET 请求都将转发给 处理程序。

名称: Assets
类型: fs.FS

处理程序​

资产处理程序是一个通用的 http.Handler,用于对无法找到的资产进行后备处理。

由于 os.ErrNotExist,对于每个无法从 资产 提供服务的 GET 请求,都会调用该处理程序。 此外,所有非 GET 请求将始终从此处理程序提供服务。 如果未定义,则调用处理程序的结果如下:

  • GET 请求: http.StatusNotFound
  • 其他请求: http.StatusMethodNotAllowed

注意:当与前端 DevServer 结合使用时,可能会有一些限制,例如。 Vite 在不包含文件扩展名的每个路径上提供 index.html。

名称:AssetsHandler
类型:http.Handler

中间件​

中间件是一个 HTTP 中间件,它允许挂钩到资产服务器请求链。 它允许动态跳过默认请求处理程序,例如实现专门的路由等。 调用中间件来构建资产服务器使用的新 http.Handler,它还接收资产服务器使用的默认处理程序作为参数。

如果未定义,则执行默认的资产服务器请求链。

名称: Middleware
类型: assetserver.Middleware

菜单​

应用程序要使用的菜单。 菜单参考 中有关菜单的更多详细信息。

备注

在 Mac 上,如果未指定菜单,将创建一个默认菜单。

名称:Menu
类型:*menu.Menu

日志​

应用程序要使用的记录器。 有关日志记录的更多详细信息,请参阅 日志参考。

名称:Logger
类型:logger.Logger
默认值:Logs to Stdout

日志级别​

默认日志级别。 有关日志记录的更多详细信息,请参阅 日志参考。

名称:LogLevel
类型:logger.LogLevel
默认值:开发模式为 Info, 生产模式为 Error

生产日志级别​

生产构建的默认日志级别。 有关日志记录的更多详细信息,请参阅 日志参考。

名称:LogLevelProduction
类型:logger.LogLevel
默认值:Error

应用启动回调​

此回调在前端创建之后调用,但在 index.html 加载之前调用。 它提供了应用程序上下文。

名称:OnStartup
类型:func(ctx context.Context)

前端 Dom 加载完成回调​

在前端加载完毕 index.html 及其资源后调用此回调。 它提供了应用程序上下文。

名称:OnDomReady
类型:func(ctx context.Context)

应用退出回调​

在前端被销毁之后,应用程序终止之前,调用此回调。 它提供了应用程序上下文。

名称:OnShutdown
类型:func(ctx context.Context)

应用关闭前回调​

如果设置了此回调,它将在通过单击窗口关闭按钮或调用runtime.Quit即将退出应用程序时被调用. 返回 true 将导致应用程序继续,false 将继续正常关闭。 返回 true 将导致应用程序继续,false 将继续正常关闭。 这有助于与用户确认他们希望退出程序。

示例:

windowsapp.go
func (b *App) beforeClose(ctx context.Context) (prevent bool) {
dialog, err := runtime.MessageDialog(ctx, runtime.MessageDialogOptions{
Type: runtime.QuestionDialog,
Title: "Quit?",
Message: "Are you sure you want to quit?",
})

if err != nil {
return false
}
return dialog != "Yes"
}

名称:OnBeforeClose
类型:func(ctx context.Context) bool

CSS 拖动属性​

指示用于标识哪些元素可用于拖动窗口的 CSS 属性。 默认值:--wails-draggable

名称:CSSDragProperty
类型:string

CSS 拖动值​

指示 CSSDragProperty 样式应该具有什么值才能拖动窗口。 默认值:drag

名称:CSSDragValue
类型:string

启用欺诈网站检测​

EnableFraudulentWebsiteDetection 启用针对欺诈内容(例如恶意软件或网络钓鱼尝试)的扫描服务。 这些服务可能会从你的应用中发送信息,比如导航到苹果和微软的云服务的url和其他内容。

名称:EnableFraudulentWebsiteDetection
类型:bool

缩放比例​

名称:ZoomFactor
类型:float64

这定义了 WebView2 的缩放比例。 这是匹配 Edge 用户激活放大或缩小的选项

启用缩放比例​

名称:IsZoomControlEnabled
类型:bool

这将允许用户更改缩放比例。 请注意,可以在选项中设置缩放比例,但不允许在运行时更改它。 适用于屏幕固定的或类似的应用程序。

绑定​

定义需要绑定到前端的方法的结构实例切片。

名称:Bind
类型:[]interface{}

Windows​

这定义了 Windows 特定的选项。

名称:Windows
类型:*windows.Options

Webview 透明​

当使用 alpha 值 0 时,将此设置为 true 将使 webview 背景透明。 这意味着如果您在 CSS 中使用 rgba(0,0,0,0) 作为 background-color,则主机窗口将显示出来。 通常与 窗口半透明 结合使用以制作看起来冷冰冰的应用程序。

名称:WebviewIsTransparent
类型:bool

窗口半透明​

将此设置为 true 将使窗口半透明。 通常与 Webview 透明 结合使用。

对于 build 22621 之前的 Windows 11 版本,将使用 BlurBehind 方法来实现半透明,这可能会很慢。 对于构建 build 22621 之后的 Windows 11 版本,这将启用速度更快的新半透明类型。 默认情况下,使用的半透明类型将由 Windows 确定。 要对此进行配置,请使用 背景类型 选项。

名称:WindowIsTranslucent
类型:bool

背景类型​

备注

需要 Windows 11 build 22621 或更高版本。

设置窗口的半透明类型。 这仅在 窗口半透明 设置为 true 时适用。

名称:BackdropType
类型:windows.BackdropType

值可以是以下之一:

值描述
Auto让 Windows 决定使用哪个背景
None不要使用半透明
Acrylic使用 亚克力 效果
Mica使用 Mica 效果
Tabbed使用 Tabbed。 这是一个类似于 Mica 的背景。

禁用窗口图标​

将此设置为 true 将删除标题栏左上角的图标。

名称:DisableWindowIcon
类型:bool

禁用无边框窗口装饰​

将此设置为 true 将移除 无边框 模式下的窗口装饰。 这意味着将不会有Aero 阴影 和 圆角显示在窗口上。 请注意,'圆角' 只在 Windows 11 上支持。

名称:DisableFramelessWindowDecorations
类型:bool

Webview 用户数据路径​

这定义了 WebView2 存储用户数据的路径。 如果为空将使用 %APPDATA%\[BinaryName.exe]。

名称:WebviewUserDataPath
类型:string

Webview 浏览器路径​

这定义了带有 WebView2 可执行文件和库的目录的路径 如果为空,则使用系统中安装的 webview2

有关固定版本运行时分发的重要信息:

名称:WebviewBrowserPath
类型:string

主题​

最低 Windows 版本:Windows 10 2004/20H1

这定义了应用程序应该使用的主题:

值描述
SystemDefault默认。 主题将基于系统默认值。 如果用户更改了他们的主题,应用程序将更新以使用新设置
Dark该应用程序将只使用深色主题
Light该应用程序将专门使用浅色主题

名称:Theme
类型:windows.Theme

自定义主题​

备注

最低 Windows 版本:Windows 10/11 2009/21H2 Build 22000

允许您为浅色和深色模式以及窗口处于活动或非活动状态的 TitleBar、TitleText 和 Border 指定自定义颜色。

名称:CustomTheme
类型:windows.CustomTheme

自定义主题类型​

CustomTheme 结构体使用 int32 指定颜色值。 它们采用标准(!)Windows 格式:0x00BBGGAA。 These are in the standard(!) Windows format of: 0x00BBGGAA. 提供了一个辅助函数来将 RGB 转换为这种格式:windows.RGB(r,g,b uint8)。

注意:任何未提供的值都将默认为黑色。

type ThemeSettings struct {
DarkModeTitleBar int32
DarkModeTitleBarInactive int32
DarkModeTitleText int32
DarkModeTitleTextInactive int32
DarkModeBorder int32
DarkModeBorderInactive int32
LightModeTitleBar int32
LightModeTitleBarInactive int32
LightModeTitleText int32
LightModeTitleTextInactive int32
LightModeBorder int32
LightModeBorderInactive int32
}

示例:

    CustomTheme: &windows.ThemeSettings{
// Theme to use when window is active
DarkModeTitleBar: windows.RGB(255, 0, 0), // Red
DarkModeTitleText: windows.RGB(0, 255, 0), // Green
DarkModeBorder: windows.RGB(0, 0, 255), // Blue
LightModeTitleBar: windows.RGB(200, 200, 200),
LightModeTitleText: windows.RGB(20, 20, 20),
LightModeBorder: windows.RGB(200, 200, 200),
// Theme to use when window is inactive
DarkModeTitleBarInactive: windows.RGB(128, 0, 0),
DarkModeTitleTextInactive: windows.RGB(0, 128, 0),
DarkModeBorderInactive: windows.RGB(0, 0, 128),
LightModeTitleBarInactive: windows.RGB(100, 100, 100),
LightModeTitleTextInactive: windows.RGB(10, 10, 10),
LightModeBorderInactive: windows.RGB(100, 100, 100),
},

消息​

一个如果找不到有效的 webview2 运行时,webview2 安装程序所使用的字符串结构。

名称:Messages
类型:*windows.Messages

您可以选择支持的任意语言定制此选项。

重置尺寸防抖间隔​

ResizeDebounceMS 是调整窗口大小时去抖动 webview2 重绘的时间量。 默认值 (0) 将尽可能快地执行重绘。

名称:ResizeDebounceMS
类型:uint16

待机回调​

如果设置,当 Windows 启动切换到低功耗模式(挂起/休眠)时将调用此函数

名称:OnSuspend
类型:func()

恢复回调​

如果设置,当 Windows 从低功耗模式(挂起/休眠)恢复时将调用此函数

名称:OnResume
类型:func()

禁用 Webview GPU 硬件加速​

设置为 true 将禁用 webview 的 GPU 硬件加速。

名称:WebviewGpuIsDisabled
类型:bool

Mac​

这定义了 Mac 特定的选项。

名称:Mac
类型:*mac.Options

标题栏​

TitleBar 结构提供了配置标题栏外观的能力。

名称:TitleBar
类型:*mac.TitleBar

标题栏结构体​

可以使用 TitleBar 选项自定义应用程序的标题栏:

type TitleBar struct {
TitlebarAppearsTransparent bool
HideTitle bool
HideTitleBar bool
FullSizeContent bool
UseToolbar bool
HideToolbarSeparator bool
}
设置描述
TitlebarAppearsTransparent使标题栏透明。 这具有隐藏标题栏和内容填充窗口的效果。 苹果文档
HideTitle隐藏窗口的标题。 苹果文档
HideTitleBar从 style mask 中删除 NSWindowStyleMaskTitled
FullSizeContent使 webview 填满整个窗口。 苹果文档
UseToolbar向窗口添加默认工具栏。 苹果文档
HideToolbarSeparator删除工具栏下方的线条。 苹果文档

预配置的标题栏设置可用:

设置示例
mac.TitleBarDefault()
mac.TitleBarHidden()
mac.TitleBarHiddenInset()

示例:

Mac: &mac.Options{
TitleBar: mac.TitleBarHiddenInset(),
}

单击 此处 获取有关自定义标题栏的一些灵感。

外观​

Appearance 用于根据 Apple 的 NSAppearance 名称设置您的应用程序的样式。

名称:Appearance
类型:mac.AppearanceType

外观类型​

您可以指定应用程序的 外观。

值描述
DefaultAppearance使用默认系统值
NSAppearanceNameAqua标准日间系统外观
NSAppearanceNameDarkAqua标准黑夜系统外观
NSAppearanceNameVibrantLight轻盈灵动的外观
NSAppearanceNameAccessibilityHighContrastAqua标准白天系统外观的高对比度版本
NSAppearanceNameAccessibilityHighContrastDarkAqua标准黑夜系统外观的高对比度版本
NSAppearanceNameAccessibilityHighContrastVibrantLight轻盈灵动外观的高对比度版本
NSAppearanceNameAccessibilityHighContrastVibrantDark深色活力外观的高对比度版本

示例:

Mac: &mac.Options{
Appearance: mac.NSAppearanceNameDarkAqua,
}

Webview 透明​

当使用 alpha 值 0 时,将此设置为 true 将使 webview 背景透明。 这意味着如果您在 CSS 中使用 rgba(0,0,0,0) 作为 background-color,则主机窗口将显示出来。 通常与 窗口半透明 结合使用以制作看起来冷冰冰的应用程序。

名称:WebviewIsTransparent
类型:bool

窗口半透明​

将此设置为 true 将使窗口半透明。 通常与Webview 透明 结合使用以制作冰霜效果的应用程序。

名称:WindowIsTranslucent
类型:bool

关于​

此配置允许您在“AppMenu”角色创建的应用程序菜单中设置“关于”菜单项的标题、消息和图标。

名称:About
类型:*mac.AboutInfo

关于结构体​

type AboutInfo struct {
Title string
Message string
Icon []byte
}

如果提供了这些设置,“关于”菜单项将出现在应用程序菜单中(使用AppMenu role 时)。 建议这样配置:

//go:embed build/appicon.png
var icon []byte

func main() {
err := wails.Run(&options.App{
...
Mac: &mac.Options{
About: &mac.AboutInfo{
Title: "My Application",
Message: "© 2021 Me",
Icon: icon,
},
},
})
Mac: &mac.Options{
About: &mac.AboutInfo{
Title: "My Application",
Message: "© 2021 Me",
Icon: icon,
},
},
})
Mac: &mac.Options{
About: &mac.AboutInfo{
Title: "My Application",
Message: "© 2021 Me",
Icon: icon,
},
},
})

“关于”菜单项将出现在应用程序菜单中:


单击后,将打开一个关于消息框:


Linux​

这定义了 Linux 特定的选项。

名称:Linux
类型:*linux.Options

图标​

设置代表窗口的图标。 当窗口最小化(也称为图标化)时使用此图标。

名称:Icon
类型:[]byte

一些窗口管理器或桌面环境也可能将其放置在窗口框架中,或在其他上下文中显示。 在其他情况下,根本不使用该图标,因此您的预计情况可能会有所不同。

注意:Wayland 上的 Gnome 至少不显示此图标。 要在那里有一个应用程序图标,必须使用一个.desktop文件。 在 KDE 上它应该可以工作。

图标应该以自然绘制的任何尺寸提供;也就是说,在传递图像之前不要缩放图像。 缩放将延迟到当所需的最终尺寸已知的最后一刻,以获得最佳质量。

窗口半透明​

将此设置为 true 将使窗口半透明。 某些窗口管理员可能忽略它,或导致黑窗口。

名称:WindowIsTranslucent
类型:bool

Webview GPU 策略​

该选项用于决定 webview 的硬件加速策略。

名称:WebviewGpuPolicy
类型:options.WebviewGpuPolicy
默认:WebviewGpuPolicyAlways

Webview GPU 策略类型​
值描述
WebviewGpuPolicyAlways始终启用硬件加速
WebviewGpuPolicyOnDemand根据 Web 内容的请求启用/禁用硬件加速
WebviewGpuPolicyNever硬件加速始终处于禁用状态

调试​

这定义了用于调试构建的 调试特定选项。

名称: Debug
类型: options.Debug

启动时打开检查器​

设置为 true 将在应用程序启动时打开 Web 检查器。

名称: OpenInspectorOnStartup
类型: bool


  1. 这需要 WebKit2GTK 2.36+ 支持,并且您的应用程序需要使用构建标签 webkit2_36 来构建以激活对此功能的支持。 这也会将您应用程序的 WebKit2GTK 最低要求提高到 2.36。↩
  2. 这需要 WebKit2GTK 2.40+ 支持,并且您的应用程序需要使用构建标签 webkit2_40 来构建以激活对此功能的支持。 这也将您的应用程序的 WebKit2GTK 最低要求提高到 2.40。↩