mirror of
https://github.com/wailsapp/wails.git
synced 2025-05-02 18:10:48 +08:00
1042 lines
36 KiB
Plaintext
1042 lines
36 KiB
Plaintext
---
|
||
sidebar_position: 3
|
||
---
|
||
|
||
# Options
|
||
|
||
## Application Options
|
||
|
||
The `Options.App` struct contains the application configuration.
|
||
It is passed to the `wails.Run()` method:
|
||
|
||
```go title="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",
|
||
EnableDefaultContextMenu: false,
|
||
EnableFraudulentWebsiteDetection: false,
|
||
Bind: []interface{}{
|
||
app,
|
||
},
|
||
EnumBind: []interface{}{
|
||
AllWeekdays,
|
||
},
|
||
ErrorFormatter: func(err error) any { return err.Error() },
|
||
SingleInstanceLock: &options.SingleInstanceLock{
|
||
UniqueId: "c9c8fd93-6758-4144-87d1-34bdb0a8bd60",
|
||
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
|
||
},
|
||
Windows: &windows.Options{
|
||
WebviewIsTransparent: false,
|
||
WindowIsTranslucent: false,
|
||
BackdropType: windows.Mica,
|
||
DisablePinchZoom: false,
|
||
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),
|
||
},
|
||
// ZoomFactor is the zoom factor for the WebView2. This is the option matching the Edge user activated zoom in or out.
|
||
ZoomFactor: float64,
|
||
// IsZoomControlEnabled enables the zoom factor to be changed by the user.
|
||
IsZoomControlEnabled: bool,
|
||
// 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(),
|
||
// Disable GPU hardware acceleration for the webview
|
||
WebviewGpuDisabled: false,
|
||
},
|
||
Mac: &mac.Options{
|
||
TitleBar: &mac.TitleBar{
|
||
TitlebarAppearsTransparent: true,
|
||
HideTitle: false,
|
||
HideTitleBar: false,
|
||
FullSizeContent: false,
|
||
UseToolbar: false,
|
||
HideToolbarSeparator: true,
|
||
OnFileOpen: app.onFileOpen,
|
||
OnUrlOpen: app.onUrlOpen,
|
||
},
|
||
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,
|
||
ProgramName: "wails"
|
||
},
|
||
Debug: options.Debug{
|
||
OpenInspectorOnStartup: false,
|
||
},
|
||
})
|
||
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
}
|
||
|
||
```
|
||
|
||
### Title
|
||
|
||
The text shown in the window's title bar.
|
||
|
||
Name: Title<br/>
|
||
Type: `string`
|
||
|
||
### Width
|
||
|
||
The initial width of the window.
|
||
|
||
Name: Width<br/>
|
||
Type: `int`<br/>
|
||
Default: 1024.
|
||
|
||
### Height
|
||
|
||
The initial height of the window.
|
||
|
||
Name: Height<br/>
|
||
Type: `int`<br/>
|
||
Default: 768
|
||
|
||
### DisableResize
|
||
|
||
By default, the main window is resizable. Setting this to `true` will keep it a fixed size.
|
||
|
||
Name: DisableResize<br/>
|
||
Type: `bool`
|
||
|
||
### Fullscreen
|
||
|
||
Deprecated: Please use [WindowStartState](#windowstartstate).
|
||
|
||
### WindowStartState
|
||
|
||
Defines how the window should present itself at startup.
|
||
|
||
| Value | Win | Mac | Lin |
|
||
| ---------- | --- | --- | --- |
|
||
| Fullscreen | ✅ | ✅ | ✅ |
|
||
| Maximised | ✅ | ✅ | ✅ |
|
||
| Minimised | ✅ | ❌ | ✅ |
|
||
|
||
Name: WindowStartState<br/>
|
||
Type: `options.WindowStartState`
|
||
|
||
### Frameless
|
||
|
||
When set to `true`, the window will have no borders or title bar.
|
||
Also see [Frameless Windows](../guides/frameless.mdx).
|
||
|
||
Name: Frameless<br/>
|
||
Type: `bool`
|
||
|
||
### MinWidth
|
||
|
||
This sets the minimum width for the window. If the value given in `Width` is less than this value,
|
||
the window will be set to `MinWidth` by default.
|
||
|
||
Name: MinWidth<br/>
|
||
Type: `int`
|
||
|
||
### MinHeight
|
||
|
||
This sets the minimum height for the window. If the value given in `Height` is less than this value,
|
||
the window will be set to `MinHeight` by default.
|
||
|
||
Name: MinHeight<br/>
|
||
Type: `int`
|
||
|
||
### MaxWidth
|
||
|
||
This sets the maximum width for the window. If the value given in `Width` is more than this value,
|
||
the window will be set to `MaxWidth` by default.
|
||
|
||
Name: MaxWidth<br/>
|
||
Type: `int`
|
||
|
||
### MaxHeight
|
||
|
||
This sets the maximum height for the window. If the value given in `Height` is more than this value,
|
||
the window will be set to `MaxHeight` by default.
|
||
|
||
Name: MaxHeight<br/>
|
||
Type: `int`
|
||
|
||
### StartHidden
|
||
|
||
When set to `true`, the application will be hidden until [WindowShow](../reference/runtime/window.mdx#windowshow)
|
||
is called.
|
||
|
||
Name: StartHidden<br/>
|
||
Type: `bool`
|
||
|
||
### HideWindowOnClose
|
||
|
||
By default, closing the window will close the application. Setting this to `true` means closing the window will
|
||
|
||
hide the window instead.
|
||
|
||
Name: HideWindowOnClose<br/>
|
||
Type: `bool`
|
||
|
||
### BackgroundColour
|
||
|
||
This value is the default background colour of the window.
|
||
Example: options.NewRGBA(255,0,0,128) - Red at 50% transparency
|
||
|
||
Name: BackgroundColour<br/>
|
||
Type: `*options.RGBA`<br/>
|
||
Default: white
|
||
|
||
### AlwaysOnTop
|
||
|
||
Indicates that the window should stay above other windows when losing focus.
|
||
|
||
Name: AlwaysOnTop<br/>
|
||
Type: `bool`
|
||
|
||
### Assets
|
||
|
||
Deprecated: Please use Assets on [AssetServer specific options](#assetserver).
|
||
|
||
### AssetsHandler
|
||
|
||
Deprecated: Please use AssetsHandler on [AssetServer specific options](#assetserver).
|
||
|
||
### AssetServer
|
||
|
||
This defines AssetServer specific options. It allows to customize the AssetServer with static assets, serving assets
|
||
dynamically with an `http.Handler` or hook into the request chain with an `assetserver.Middleware`.
|
||
|
||
Not all features of an `http.Request` are currently supported, please see the following feature matrix:
|
||
|
||
| Feature | Win | Mac | Lin |
|
||
| ----------------------- | --- | --- | ------ |
|
||
| 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 | ✅ | ❌ | ❌ |
|
||
|
||
[^1]: This requires WebKit2GTK 2.36+ support and your app needs to be build with the build tag `webkit2_36` to activate support for this feature. This also bumps the minimum requirement of WebKit2GTK to 2.36 for your app.
|
||
[^2]: This requires WebKit2GTK 2.40+ support and your app needs to be build with the build tag `webkit2_40` to activate support for this feature. This also bumps the minimum requirement of WebKit2GTK to 2.40 for your app.
|
||
|
||
Name: AssetServer<br/>
|
||
Type: `*assetserver.Options`
|
||
|
||
#### Assets
|
||
|
||
The static frontend assets to be used by the application.
|
||
|
||
A GET request is first tried to be served from this `fs.FS`. If the `fs.FS` returns `os.ErrNotExist` for that file,
|
||
the request handling will fallback to the [Handler](#handler) and tries to serve the GET request from it.
|
||
|
||
If set to nil, all GET requests will be forwarded to [Handler](#handler).
|
||
|
||
Name: Assets<br/>
|
||
Type: `fs.FS`
|
||
|
||
#### Handler
|
||
|
||
The assets handler is a generic `http.Handler` for fallback handling of assets that can't be found.
|
||
|
||
The handler will be called for every GET request that can't be served from [Assets](#assets), due to `os.ErrNotExist`.
|
||
Furthermore all non GET requests will always be served from this Handler.
|
||
If not defined, the result is the following in cases where the Handler would have been called:
|
||
|
||
- GET request: `http.StatusNotFound`
|
||
- Other request: `http.StatusMethodNotAllowed`
|
||
|
||
:::info
|
||
|
||
This does not work with vite v5.0.0+ and wails v2 due to changes in vite.
|
||
Changes are planned in v3 to support similar functionality under vite v5.0.0+.
|
||
If you need this feature, stay with vite v4.0.0+.
|
||
See [issue 3240](https://github.com/wailsapp/wails/issues/3240) for details
|
||
|
||
:::
|
||
|
||
NOTE: When used in combination with a Frontend DevServer there might be limitations, eg. Vite serves the index.html
|
||
on every path, that does not contain a file extension.
|
||
|
||
Name: AssetsHandler<br/>
|
||
Type: `http.Handler`
|
||
|
||
#### Middleware
|
||
|
||
Middleware is a HTTP Middleware which allows to hook into the AssetServer request chain. It allows to skip the default
|
||
request handler dynamically, e.g. implement specialized Routing etc.
|
||
The Middleware is called to build a new `http.Handler` used by the AssetSever and it also receives the default
|
||
handler used by the AssetServer as an argument.
|
||
|
||
If not defined, the default AssetServer request chain is executed.
|
||
|
||
Name: Middleware<br/>
|
||
Type: `assetserver.Middleware`
|
||
|
||
### Menu
|
||
|
||
The menu to be used by the application. More details about Menus in the [Menu Reference](../reference/runtime/menu.mdx).
|
||
|
||
:::note
|
||
|
||
On Mac, if no menu is specified, a default menu will be created.
|
||
|
||
:::
|
||
|
||
Name: Menu<br/>
|
||
Type: `*menu.Menu`
|
||
|
||
### Logger
|
||
|
||
The logger to be used by the application. More details about logging in the [Log Reference](../reference/runtime/log.mdx).
|
||
|
||
Name: Logger<br/>
|
||
Type: `logger.Logger`<br/>
|
||
Default: Logs to Stdout
|
||
|
||
### LogLevel
|
||
|
||
The default log level. More details about logging in the [Log Reference](../reference/runtime/log.mdx).
|
||
|
||
Name: LogLevel<br/>
|
||
Type: `logger.LogLevel`<br/>
|
||
Default: `Info` in dev mode, `Error` in production mode
|
||
|
||
### LogLevelProduction
|
||
|
||
The default log level for production builds. More details about logging in the [Log Reference](../reference/runtime/log.mdx).
|
||
|
||
Name: LogLevelProduction<br/>
|
||
Type: `logger.LogLevel`<br/>
|
||
Default: `Error`
|
||
|
||
### OnStartup
|
||
|
||
This callback is called after the frontend has been created, but before `index.html` has been loaded. It is given
|
||
the application context.
|
||
|
||
Name: OnStartup<br/>
|
||
Type: `func(ctx context.Context)`
|
||
|
||
### OnDomReady
|
||
|
||
This callback is called after the frontend has loaded `index.html` and its resources. It is given
|
||
the application context.
|
||
|
||
Name: OnDomReady<br/>
|
||
Type: `func(ctx context.Context)`
|
||
|
||
### OnShutdown
|
||
|
||
This callback is called after the frontend has been destroyed, just before the application terminates. It is given
|
||
the application context.
|
||
|
||
Name: OnShutdown<br/>
|
||
Type: `func(ctx context.Context)`
|
||
|
||
### OnBeforeClose
|
||
|
||
If this callback is set, it will be called when the application is about to quit, either by clicking the window close
|
||
button or calling `runtime.Quit`. Returning true will cause the application to continue, false will continue shutdown
|
||
as normal. This is good for confirming with the user that they wish to exit the program.
|
||
|
||
Example:
|
||
|
||
```go title=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"
|
||
}
|
||
```
|
||
|
||
Name: OnBeforeClose<br/>
|
||
Type: `func(ctx context.Context) bool`
|
||
|
||
### CSSDragProperty
|
||
|
||
Indicates the CSS property to use to identify which elements can be used to drag the window. Default: `--wails-draggable`.
|
||
|
||
Name: CSSDragProperty<br/>
|
||
Type: `string`
|
||
|
||
### CSSDragValue
|
||
|
||
Indicates what value the `CSSDragProperty` style should have to drag the window. Default: `drag`.
|
||
|
||
Name: CSSDragValue<br/>
|
||
Type: `string`
|
||
|
||
### EnableDefaultContextMenu
|
||
|
||
EnableDefaultContextMenu enables the browser's default context-menu in production.
|
||
|
||
By default, the browser's default context-menu is only available in development and in a `-debug` [build](../reference/cli.mdx#build) along with the devtools inspector, Using this option you can enable the default context-menu in `production` while the devtools inspector won't be available unless the `-devtools` build flag is used.
|
||
|
||
When this option is enabled, by default the context-menu will only be shown for text contexts (where Cut/Copy/Paste is needed), to override this behavior, you can use the CSS property `--default-contextmenu` on any HTML element (including the `body`) with the following values :
|
||
|
||
| CSS Style | Behavior |
|
||
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `--default-contextmenu: auto;` | (**default**) will show the default context menu only if :<br/> contentEditable is true OR text has been selected OR element is input or textarea |
|
||
| `--default-contextmenu: show;` | will always show the default context menu |
|
||
| `--default-contextmenu: hide;` | will always hide the default context menu |
|
||
|
||
This rule is inherited like any normal CSS rule, so nesting works as expected.
|
||
|
||
:::note
|
||
This filtering functionality is only enabled in production, so in development and in debug build, the full context-menu is always available everywhere.
|
||
:::
|
||
|
||
:::warning
|
||
This filtering functionality is NOT a security measure, the developer should expect that the full context-menu could be leaked anytime which could contain commands like (Download image, Reload, Save webpage), if this is a concern, the developer SHOULD NOT enable the default context-menu.
|
||
:::
|
||
|
||
|
||
Name: EnableDefaultContextMenu<br/>
|
||
Type: `bool`
|
||
|
||
### EnableFraudulentWebsiteDetection
|
||
|
||
EnableFraudulentWebsiteDetection enables scan services for fraudulent content, such as malware or phishing attempts.
|
||
These services might send information from your app like URLs navigated to and possibly other content to cloud
|
||
services of Apple and Microsoft.
|
||
|
||
Name: EnableFraudulentWebsiteDetection<br/>
|
||
Type: `bool`
|
||
|
||
### ZoomFactor
|
||
|
||
Name: ZoomFactor<br/>
|
||
Type: `float64`
|
||
|
||
This defines the zoom factor for the WebView2. This is the option matching the Edge user activated zoom in or out.
|
||
|
||
### IsZoomControlEnabled
|
||
|
||
Name: IsZoomControlEnabled<br/>
|
||
Type: `bool`
|
||
|
||
This enables the zoom factor to be changed by the user. Please note that the zoom factor can be set in the options while
|
||
disallowing the user to change it at runtime (f.e. for a kiosk application or similar).
|
||
|
||
### Bind
|
||
|
||
A slice of struct instances defining methods that need to be bound to the frontend.
|
||
|
||
Name: Bind<br/>
|
||
Type: `[]interface{}`
|
||
|
||
### EnumBind
|
||
|
||
A slice of Enum arrays that need to be bound to the frontend.
|
||
|
||
Name: EnumBind<br/>
|
||
Type: `[]interface{}`
|
||
|
||
### ErrorFormatter
|
||
|
||
A function that determines how errors are formatted when returned by a JS-to-Go
|
||
method call. The returned value will be marshalled as JSON.
|
||
|
||
Name: ErrorFormatter<br/>
|
||
Type: `func (error) any`
|
||
|
||
### SingleInstanceLock
|
||
|
||
Enables single instance locking. This means that only one instance of your application can be running at a time.
|
||
|
||
Name: SingleInstanceLock<br/>
|
||
Type: `*options.SingleInstanceLock`
|
||
|
||
#### UniqueId
|
||
|
||
This id is used to generate the mutex name on Windows and macOS and the dbus name on Linux. Use a UUID to ensure that the id is unique.
|
||
|
||
Name: UniqueId<br/>
|
||
Type: `string`
|
||
|
||
#### OnSecondInstanceLaunch
|
||
|
||
Callback that is called when a second instance of your app is launched.
|
||
|
||
Name: OnSecondInstanceLaunch<br/>
|
||
Type: `func(secondInstanceData SecondInstanceData)`
|
||
|
||
|
||
### Windows
|
||
|
||
This defines [Windows specific options](#windows).
|
||
|
||
Name: Windows<br/>
|
||
Type: `*windows.Options`
|
||
|
||
#### WebviewIsTransparent
|
||
|
||
Setting this to `true` will make the webview background transparent when an alpha value of `0` is used.
|
||
This means that if you use `rgba(0,0,0,0)` for `background-color` in your CSS, the host window will show through.
|
||
Often combined with [WindowIsTranslucent](#WindowIsTranslucent) to make frosty-looking applications.
|
||
|
||
Name: WebviewIsTransparent<br/>
|
||
Type: `bool`
|
||
|
||
#### WindowIsTranslucent
|
||
|
||
Setting this to `true` will make the window background translucent. Often combined
|
||
with [WebviewIsTransparent](#WebviewIsTransparent).
|
||
|
||
For Windows 11 versions before build 22621, this will use the [BlurBehind](https://learn.microsoft.com/en-us/windows/win32/dwm/blur-ovw)
|
||
method for translucency, which can be slow. For Windows 11 versions after build 22621, this will enable the
|
||
newer translucency types that are much faster. By default, the type of translucency used will be determined
|
||
by Windows. To configure this, use the [BackdropType](#BackdropType) option.
|
||
|
||
Name: WindowIsTranslucent<br/>
|
||
Type: `bool`
|
||
|
||
#### BackdropType
|
||
|
||
:::note
|
||
|
||
Requires Windows 11 build 22621 or later.
|
||
|
||
:::
|
||
|
||
Sets the translucency type of the window. This is only applicable if [WindowIsTranslucent](#WindowIsTranslucent) is set to `true`.
|
||
|
||
Name: BackdropType<br/>
|
||
Type `windows.BackdropType`
|
||
|
||
The value can be one of the following:
|
||
|
||
| Value | Description |
|
||
| ------- | ----------------------------------------------------------------------------------------- |
|
||
| Auto | Let Windows decide which backdrop to use |
|
||
| None | Do not use translucency |
|
||
| Acrylic | Use [Acrylic](https://learn.microsoft.com/en-us/windows/apps/design/style/acrylic) effect |
|
||
| Mica | Use [Mica](https://learn.microsoft.com/en-us/windows/apps/design/style/mica) effect |
|
||
| Tabbed | Use Tabbed. This is a backdrop that is similar to Mica. |
|
||
|
||
#### DisablePinchZoom
|
||
|
||
Setting this to `true` will disable pinch zoom gestures.
|
||
|
||
Name: DisablePinchZoom<br/>
|
||
Type: `bool`
|
||
|
||
#### DisableWindowIcon
|
||
|
||
Setting this to `true` will remove the icon in the top left corner of the title bar.
|
||
|
||
Name: DisableWindowIcon<br/>
|
||
Type: `bool`
|
||
|
||
#### DisableFramelessWindowDecorations
|
||
|
||
Setting this to `true` will remove the window decorations in [Frameless](#Frameless) mode. This means there will be no
|
||
'Aero Shadow' and no 'Rounded Corners' shown for the window. Please note that 'Rounded Corners' are only supported on
|
||
Windows 11.
|
||
|
||
Name: DisableFramelessWindowDecorations<br/>
|
||
Type: `bool`
|
||
|
||
#### WebviewUserDataPath
|
||
|
||
This defines the path where the WebView2 stores the user data. If empty `%APPDATA%\[BinaryName.exe]` will be used.
|
||
|
||
Name: WebviewUserDataPath<br/>
|
||
Type: `string`
|
||
|
||
#### WebviewBrowserPath
|
||
|
||
This defines the path to a directory with WebView2 executable files and libraries. If empty, webview2 installed in the system will be used.
|
||
|
||
Important information about distribution of fixed version runtime:
|
||
|
||
- [How to get and extract runtime](https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution#details-about-the-fixed-version-runtime-distribution-mode)
|
||
- [Known issues for fixed version](https://docs.microsoft.com/en-us/microsoft-edge/webview2/concepts/distribution#known-issues-for-fixed-version)
|
||
- [The path of fixed version of the WebView2 Runtime should not contain \Edge\Application\.](https://docs.microsoft.com/en-us/microsoft-edge/webview2/reference/win32/webview2-idl?view=webview2-1.0.1245.22#createcorewebview2environmentwithoptions)
|
||
|
||
Name: WebviewBrowserPath<br/>
|
||
Type: `string`
|
||
|
||
#### Theme
|
||
|
||
Minimum Windows Version: Windows 10 2004/20H1
|
||
|
||
This defines the theme that the application should use:
|
||
|
||
| Value | Description |
|
||
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| SystemDefault | _Default_. The theme will be based on the system default. If the user changes their theme, the application will update to use the new setting |
|
||
| Dark | The application will use a dark theme exclusively |
|
||
| Light | The application will use a light theme exclusively |
|
||
|
||
Name: Theme<br/>
|
||
Type: `windows.Theme`
|
||
|
||
#### CustomTheme
|
||
|
||
:::note
|
||
|
||
Minimum Windows Version: Windows 10/11 2009/21H2 Build 22000
|
||
|
||
:::
|
||
|
||
Allows you to specify custom colours for TitleBar, TitleText and Border for both light and dark mode, as well as
|
||
when the window is active or inactive.
|
||
|
||
Name: CustomTheme<br/>
|
||
Type: `windows.CustomTheme`
|
||
|
||
##### CustomTheme type
|
||
|
||
The CustomTheme struct uses `int32` to specify the colour values. These are in the standard(!) Windows format of:
|
||
`0x00BBGGAA`. A helper function is provided to do RGB conversions into this format: `windows.RGB(r,g,b uint8)`.
|
||
|
||
NOTE: Any value not provided will default to black.
|
||
|
||
```go
|
||
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
|
||
}
|
||
```
|
||
|
||
Example:
|
||
|
||
```go
|
||
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),
|
||
},
|
||
```
|
||
|
||
#### Messages
|
||
|
||
A struct of strings used by the webview2 installer if a valid webview2 runtime is not found.
|
||
|
||
Name: Messages<br/>
|
||
Type: `*windows.Messages`
|
||
|
||
Customise this for any language you choose to support.
|
||
|
||
#### ResizeDebounceMS
|
||
|
||
ResizeDebounceMS is the amount of time to debounce redraws of webview2 when resizing the window.
|
||
The default value (0) will perform redraws as fast as it can.
|
||
|
||
Name: ResizeDebounceMS<br/>
|
||
Type: `uint16`
|
||
|
||
#### OnSuspend
|
||
|
||
If set, this function will be called when Windows initiates a switch to low power mode (suspend/hibernate)
|
||
|
||
Name: OnSuspend<br/>
|
||
Type: `func()`
|
||
|
||
#### OnResume
|
||
|
||
If set, this function will be called when Windows resumes from low power mode (suspend/hibernate)
|
||
|
||
Name: OnResume<br/>
|
||
Type: `func()`
|
||
|
||
#### WebviewGpuIsDisabled
|
||
|
||
Setting this to `true` will disable GPU hardware acceleration for the webview.
|
||
|
||
Name: WebviewGpuIsDisabled<br/>
|
||
Type: `bool`
|
||
|
||
#### EnableSwipeGestures
|
||
|
||
Setting this to `true` will enable swipe gestures for the webview.
|
||
|
||
Name: EnableSwipeGestures<br/>
|
||
Type: `bool`
|
||
|
||
### Mac
|
||
|
||
This defines [Mac specific options](#mac).
|
||
|
||
Name: Mac<br/>
|
||
Type: `*mac.Options`
|
||
|
||
#### TitleBar
|
||
|
||
The TitleBar struct provides the ability to configure the look and feel of the title bar.
|
||
|
||
Name: TitleBar<br/>
|
||
Type: [`*mac.TitleBar`](#titlebar-struct)
|
||
|
||
##### Titlebar struct
|
||
|
||
The titlebar of the application can be customised by using the TitleBar options:
|
||
|
||
```go
|
||
type TitleBar struct {
|
||
TitlebarAppearsTransparent bool
|
||
HideTitle bool
|
||
HideTitleBar bool
|
||
FullSizeContent bool
|
||
UseToolbar bool
|
||
HideToolbarSeparator bool
|
||
}
|
||
```
|
||
|
||
| Name | Description |
|
||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| TitlebarAppearsTransparent | Makes the titlebar transparent. This has the effect of hiding the titlebar and the content fill the window. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindow/1419167-titlebarappearstransparent?language=objc) |
|
||
| HideTitle | Hides the title of the window. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindowtitlevisibility?language=objc) |
|
||
| HideTitleBar | Removes [NSWindowStyleMaskTitled](https://developer.apple.com/documentation/appkit/nswindowstylemask/nswindowstylemasktitled/) from the style mask |
|
||
| FullSizeContent | Makes the webview fill the entire window. [Apple Docs](https://developer.apple.com/documentation/appkit/nswindowstylemask/nswindowstylemaskfullsizecontentview) |
|
||
| UseToolbar | Adds a default toolbar to the window. [Apple Docs](https://developer.apple.com/documentation/appkit/nstoolbar?language=objc) |
|
||
| HideToolbarSeparator | Removes the line beneath the toolbar. [Apple Docs](https://developer.apple.com/documentation/appkit/nstoolbar/1516954-showsbaselineseparator?language=objc) |
|
||
|
||
Preconfigured titlebar settings are available:
|
||
|
||
| Setting | Example |
|
||
| --------------------------- | ---------------------------------------------- |
|
||
| `mac.TitleBarDefault()` |  |
|
||
| `mac.TitleBarHidden()` |  |
|
||
| `mac.TitleBarHiddenInset()` |  |
|
||
|
||
Example:
|
||
|
||
```go
|
||
Mac: &mac.Options{
|
||
TitleBar: mac.TitleBarHiddenInset(),
|
||
}
|
||
```
|
||
|
||
Click [here](https://github.com/lukakerr/NSWindowStyles) for some inspiration on customising the titlebar.
|
||
|
||
#### Appearance
|
||
|
||
Appearance is used to set the style of your app in accordance with Apple's [NSAppearance](https://developer.apple.com/documentation/appkit/nsappearancename?language=objc) names.
|
||
|
||
Name: Appearance<br/>
|
||
Type: [`mac.AppearanceType`](#appearance-type)
|
||
|
||
##### Appearance type
|
||
|
||
You can specify the application's [appearance](https://developer.apple.com/documentation/appkit/nsappearance?language=objc).
|
||
|
||
| Value | Description |
|
||
| ----------------------------------------------------- | --------------------------------------------------------------- |
|
||
| DefaultAppearance | DefaultAppearance uses the default system value |
|
||
| NSAppearanceNameAqua | The standard light system appearance |
|
||
| NSAppearanceNameDarkAqua | The standard dark system appearance |
|
||
| NSAppearanceNameVibrantLight | The light vibrant appearance |
|
||
| NSAppearanceNameAccessibilityHighContrastAqua | A high-contrast version of the standard light system appearance |
|
||
| NSAppearanceNameAccessibilityHighContrastDarkAqua | A high-contrast version of the standard dark system appearance |
|
||
| NSAppearanceNameAccessibilityHighContrastVibrantLight | A high-contrast version of the light vibrant appearance |
|
||
| NSAppearanceNameAccessibilityHighContrastVibrantDark | A high-contrast version of the dark vibrant appearance |
|
||
|
||
Example:
|
||
|
||
```go
|
||
Mac: &mac.Options{
|
||
Appearance: mac.NSAppearanceNameDarkAqua,
|
||
}
|
||
```
|
||
|
||
#### WebviewIsTransparent
|
||
|
||
Setting this to `true` will make the webview background transparent when an alpha value of `0` is used.
|
||
This means that if you use `rgba(0,0,0,0)` for `background-color` in your CSS, the host window will show through.
|
||
Often combined with [WindowIsTranslucent](#WindowIsTranslucent) to make frosty-looking applications.
|
||
|
||
Name: WebviewIsTransparent<br/>
|
||
Type: `bool`
|
||
|
||
#### WindowIsTranslucent
|
||
|
||
Setting this to `true` will make the window background translucent. Often combined
|
||
with [WebviewIsTransparent](#WebviewIsTransparent) to make frosty-looking applications.
|
||
|
||
Name: WindowIsTranslucent<br/>
|
||
Type: `bool`
|
||
|
||
#### OnFileOpen
|
||
|
||
Callback that is called when a file is opened with the application.
|
||
|
||
Name: OnFileOpen<br/>
|
||
Type: `func(filePath string)`
|
||
|
||
#### OnUrlOpen
|
||
|
||
Callback that is called when a URL is opened with the application.
|
||
|
||
Name: OnUrlOpen<br/>
|
||
Type: `func(filePath string)`
|
||
|
||
#### Preferences
|
||
|
||
The Preferences struct provides the ability to configure the Webview preferences.
|
||
|
||
Name: Preferences<br/>
|
||
Type: [`*mac.Preferences`](#preferences-struct)
|
||
|
||
##### Preferences struct
|
||
|
||
You can specify the webview preferences.
|
||
|
||
```go
|
||
type Preferences struct {
|
||
TabFocusesLinks u.Bool
|
||
TextInteractionEnabled u.Bool
|
||
FullscreenEnabled u.Bool
|
||
}
|
||
```
|
||
|
||
| Name | Description |
|
||
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| TabFocusesLinks | A Boolean value that indicates whether pressing the tab key changes the focus to links and form controls. [Apple Docs](https://developer.apple.com/documentation/webkit/wkpreferences/2818595-tabfocuseslinks?language=objc) |
|
||
| TextInteractionEnabled | A Boolean value that indicates whether to allow people to select or otherwise interact with text. [Apple Docs](https://developer.apple.com/documentation/webkit/wkpreferences/3727362-textinteractionenabled?language=objc) |
|
||
| FullscreenEnabled | A Boolean value that indicates whether a web view can display content full screen. [Apple Docs](https://developer.apple.com/documentation/webkit/wkpreferences/3917769-elementfullscreenenabled?language=objc) |
|
||
|
||
Example:
|
||
|
||
```go
|
||
Mac: &mac.Options{
|
||
Preferences: &mac.Preferences{
|
||
TabFocusesLinks: mac.Enabled,
|
||
TextInteractionEnabled: mac.Disabled,
|
||
FullscreenEnabled: mac.Enabled,
|
||
}
|
||
}
|
||
```
|
||
|
||
#### About
|
||
|
||
This configuration lets you set the title, message and icon for the "About" menu item in the app menu created by the "AppMenu" role.
|
||
|
||
Name: About<br/>
|
||
Type: [`*mac.AboutInfo`](#about-struct)
|
||
|
||
##### About struct
|
||
|
||
```go
|
||
|
||
type AboutInfo struct {
|
||
Title string
|
||
Message string
|
||
Icon []byte
|
||
}
|
||
```
|
||
|
||
If these settings are provided, an "About" menu item will appear in the app menu (when using the `AppMenu` role).
|
||
Given this configuration:
|
||
|
||
```go
|
||
//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,
|
||
},
|
||
},
|
||
})
|
||
```
|
||
|
||
The "About" menu item will appear in the app menu:
|
||
|
||
```mdx-code-block
|
||
<div class="text--center">
|
||
<img
|
||
src={require("@site/static/img/reference/about-menu.webp").default}
|
||
class="screenshot"
|
||
/>
|
||
</div>
|
||
<br />
|
||
```
|
||
|
||
When clicked, that will open an about message box:
|
||
|
||
```mdx-code-block
|
||
<div class="text--center">
|
||
<img
|
||
src={require("@site/static/img/reference/about-dialog.webp").default}
|
||
width="40%"
|
||
class="screenshot"
|
||
/>
|
||
</div>
|
||
<br />
|
||
```
|
||
|
||
### Linux
|
||
|
||
This defines [Linux specific options](#linux).
|
||
|
||
Name: Linux<br/>
|
||
Type: `*linux.Options`
|
||
|
||
#### Icon
|
||
|
||
Sets up the icon representing the window. This icon is used when the window is minimized (also known as iconified).
|
||
|
||
Name: Icon<br/>
|
||
Type: `[]byte`
|
||
|
||
Some window managers or desktop environments may also place it in the window frame, or display it in other contexts.
|
||
On others, the icon is not used at all, so your mileage may vary.
|
||
|
||
NOTE: Gnome on Wayland at least does not display this icon. To have a application icon there, a `.desktop` file has to be used.
|
||
On KDE it should work.
|
||
|
||
The icon should be provided in whatever size it was naturally drawn; that is, don’t scale the image before passing it.
|
||
Scaling is postponed until the last minute, when the desired final size is known, to allow best quality.
|
||
|
||
#### WindowIsTranslucent
|
||
|
||
Setting this to `true` will make the window background translucent. Some window managers may ignore it, or result in a black window.
|
||
|
||
Name: WindowIsTranslucent<br/>
|
||
Type: `bool`
|
||
|
||
#### WebviewGpuPolicy
|
||
|
||
This option is used for determining the webview's hardware acceleration policy.
|
||
|
||
Name: WebviewGpuPolicy<br/>
|
||
Type: [`options.WebviewGpuPolicy`](#webviewgpupolicy-type)<br/>
|
||
Default: `WebviewGpuPolicyAlways`
|
||
|
||
##### WebviewGpuPolicy type
|
||
|
||
| Value | Description |
|
||
| -------------------------| ----------- |
|
||
| WebviewGpuPolicyAlways | Hardware acceleration is always enabled|
|
||
| WebviewGpuPolicyOnDemand | Hardware acceleration is enabled/disabled as request by web contents|
|
||
| WebviewGpuPolicyNever | Hardware acceleration is always disabled |
|
||
|
||
#### ProgramName
|
||
|
||
This option is used to set the program's name for the window manager via GTK's g_set_prgname().
|
||
This name should not be localized, [see the docs](https://docs.gtk.org/glib/func.set_prgname.html).
|
||
|
||
When a .desktop file is created this value helps with window grouping and desktop icons when the .desktop file's `Name`
|
||
property differs form the executable's filename.
|
||
|
||
Name: ProgramName<br/>
|
||
Type: string<br/>
|
||
|
||
### Debug
|
||
|
||
This defines [Debug specific options](#Debug) that apply to debug builds.
|
||
|
||
Name: Debug<br/>
|
||
Type: `options.Debug`
|
||
|
||
#### OpenInspectorOnStartup
|
||
|
||
Setting this to `true` will open the WebInspector on startup of the application.
|
||
|
||
Name: OpenInspectorOnStartup<br/>
|
||
Type: `bool`
|