github/wails
5
0
Fork 0
mirror of https://github.com/wailsapp/wails.git synced 2025-05-19 02:19:31 +08:00
Code Projects Activity

Refactor docs

Browse Source
This commit is contained in:
Lea Anthony 2024-03-18 20:47:33 +11:00
parent 98aff7778e
commit c5bb4c7405
39 changed files with 684 additions and 7118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

226
mkdocs-website/docs/en/API/application.md
View File

@ -133,227 +133,19 @@ API: `Show()`
app.Show()
```
### NewWebviewWindow
--8<--
./docs/en/API/application_window.md
./docs/en/API/application_menu.md
./docs/en/API/application_dialogs.md
./docs/en/API/application_events.md
./docs/en/API/application_screens.md
--8<--
API: `NewWebviewWindow() *WebviewWindow`
`NewWebviewWindow()` creates a new Webview window with default options, and
returns it.
```go
// Create a new webview window
window := app.NewWebviewWindow()
```
### NewWebviewWindowWithOptions
API:
`NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow`
`NewWebviewWindowWithOptions()` creates a new webview window with custom
options. The newly created window is added to a map of windows managed by the
application.
```go
// Create a new webview window with custom options
window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
Name: "Main",
Title: "My Window",
Width: 800,
Height: 600,
})
```
### OnWindowCreation
API: `OnWindowCreation(callback func(window *WebviewWindow))`
`OnWindowCreation()` registers a callback function to be called when a window is
created.
```go
// Register a callback to be called when a window is created
app.OnWindowCreation(func(window *WebviewWindow) {
// Do something
})
```
### GetWindowByName
API: `GetWindowByName(name string) *WebviewWindow`
`GetWindowByName()` fetches and returns a window with a specific name.
```go
// Get a window by name
window := app.GetWindowByName("Main")
```
### CurrentWindow
API: `CurrentWindow() *WebviewWindow`
`CurrentWindow()` fetches and returns a pointer to the currently active window
in the application. If there is no window, it returns nil.
```go
// Get the current window
window := app.CurrentWindow()
```
### RegisterContextMenu
API: `RegisterContextMenu(name string, menu *Menu)`
`RegisterContextMenu()` registers a context menu with a given name. This menu
can be used later in the application.
```go
// Create a new menu
ctxmenu := app.NewMenu()
// Register the menu as a context menu
app.RegisterContextMenu("MyContextMenu", ctxmenu)
```
### SetMenu
API: `SetMenu(menu *Menu)`
`SetMenu()` sets the menu for the application. On Mac, this will be the global
menu. For Windows and Linux, this will be the default menu for any new window
created.
```go
// Create a new menu
menu := app.NewMenu()
// Set the menu for the application
app.SetMenu(menu)
```
### ShowAboutDialog
API: `ShowAboutDialog()`
`ShowAboutDialog()` shows an "About" dialog box. It can show the application's
name, description and icon.
```go
// Show the about dialog
app.ShowAboutDialog()
```
### Info
API: `InfoDialog()`
`InfoDialog()` creates and returns a new instance of `MessageDialog` with an
`InfoDialogType`. This dialog is typically used to display informational
messages to the user.
### Question
API: `QuestionDialog()`
`QuestionDialog()` creates and returns a new instance of `MessageDialog` with a
`QuestionDialogType`. This dialog is often used to ask a question to the user
and expect a response.
### Warning
API: `WarningDialog()`
`WarningDialog()` creates and returns a new instance of `MessageDialog` with a
`WarningDialogType`. As the name suggests, this dialog is primarily used to
display warning messages to the user.
### Error
API: `ErrorDialog()`
`ErrorDialog()` creates and returns a new instance of `MessageDialog` with an
`ErrorDialogType`. This dialog is designed to be used when you need to display
an error message to the user.
### OpenFile
API: `OpenFileDialog()`
`OpenFileDialog()` creates and returns a new `OpenFileDialogStruct`. This dialog
prompts the user to select one or more files from their file system.
### SaveFile
API: `SaveFileDialog()`
`SaveFileDialog()` creates and returns a new `SaveFileDialogStruct`. This dialog
prompts the user to choose a location on their file system where a file should
be saved.
### OpenDirectory
API: `OpenDirectoryDialog()`
`OpenDirectoryDialog()` creates and returns a new instance of `MessageDialog`
with an `OpenDirectoryDialogType`. This dialog enables the user to choose a
directory from their file system.
### On
API:
`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`On()` registers an event listener for specific application events. The callback
function provided will be triggered when the corresponding event occurs. The
function returns a function that can be called to remove the listener.
### RegisterHook
API:
`RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`RegisterHook()` registers a callback to be run as a hook during specific
events. These hooks are run before listeners attached with `On()`. The function
returns a function that can be called to remove the hook.
### GetPrimaryScreen
API: `GetPrimaryScreen() (*Screen, error)`
`GetPrimaryScreen()` returns the primary screen of the system.
### GetScreens
API: `GetScreens() ([]*Screen, error)`
`GetScreens()` returns information about all screens attached to the system.
This is a brief summary of the exported methods in the provided `App` struct. Do
note that for more detailed functionality or considerations, refer to the actual
Go code or further internal documentation.
## Options
```go title="application_options.go"
```go title="pkg/application/application_options.go"
--8<--
../v3/pkg/application/options_application.go
--8<--
```
### Windows Options
```go title="application_options_windows.go"
--8<--
../v3/pkg/application/options_application_win.go
--8<--
```
### Mac Options
```go title="options_application_mac.go"
--8<--
../v3/pkg/application/options_application_mac.go
../v3/pkg/application/application_options.go
--8<--
```

67
mkdocs-website/docs/en/API/application_dialogs.md Normal file
View File

@ -0,0 +1,67 @@
### ShowAboutDialog
API: `ShowAboutDialog()`
`ShowAboutDialog()` shows an "About" dialog box. It can show the application's
name, description and icon.
```go
// Show the about dialog
app.ShowAboutDialog()
```
### Info
API: `InfoDialog()`
`InfoDialog()` creates and returns a new instance of `MessageDialog` with an
`InfoDialogType`. This dialog is typically used to display informational
messages to the user.
### Question
API: `QuestionDialog()`
`QuestionDialog()` creates and returns a new instance of `MessageDialog` with a
`QuestionDialogType`. This dialog is often used to ask a question to the user
and expect a response.
### Warning
API: `WarningDialog()`
`WarningDialog()` creates and returns a new instance of `MessageDialog` with a
`WarningDialogType`. As the name suggests, this dialog is primarily used to
display warning messages to the user.
### Error
API: `ErrorDialog()`
`ErrorDialog()` creates and returns a new instance of `MessageDialog` with an
`ErrorDialogType`. This dialog is designed to be used when you need to display
an error message to the user.
### OpenFile
API: `OpenFileDialog()`
`OpenFileDialog()` creates and returns a new `OpenFileDialogStruct`. This dialog
prompts the user to select one or more files from their file system.
### SaveFile
API: `SaveFileDialog()`
`SaveFileDialog()` creates and returns a new `SaveFileDialogStruct`. This dialog
prompts the user to choose a location on their file system where a file should
be saved.
### OpenDirectory
API: `OpenDirectoryDialog()`
`OpenDirectoryDialog()` creates and returns a new instance of `MessageDialog`
with an `OpenDirectoryDialogType`. This dialog enables the user to choose a
directory from their file system.

18
mkdocs-website/docs/en/API/application_events.md Normal file
View File

@ -0,0 +1,18 @@
### On
API:
`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`On()` registers an event listener for specific application events. The callback
function provided will be triggered when the corresponding event occurs. The
function returns a function that can be called to remove the listener.
### RegisterHook
API:
`RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`RegisterHook()` registers a callback to be run as a hook during specific
events. These hooks are run before listeners attached with `On()`. The function
returns a function that can be called to remove the hook.

31
mkdocs-website/docs/en/API/application_menu.md Normal file
View File

@ -0,0 +1,31 @@
### RegisterContextMenu
API: `RegisterContextMenu(name string, menu *Menu)`
`RegisterContextMenu()` registers a context menu with a given name. This menu
can be used later in the application.
```go
// Create a new menu
ctxmenu := app.NewMenu()
// Register the menu as a context menu
app.RegisterContextMenu("MyContextMenu", ctxmenu)
```
### SetMenu
API: `SetMenu(menu *Menu)`
`SetMenu()` sets the menu for the application. On Mac, this will be the global
menu. For Windows and Linux, this will be the default menu for any new window
created.
```go
// Create a new menu
menu := app.NewMenu()
// Set the menu for the application
app.SetMenu(menu)
```

15
mkdocs-website/docs/en/API/application_screens.md Normal file
View File

@ -0,0 +1,15 @@
### GetPrimaryScreen
API: `GetPrimaryScreen() (*Screen, error)`
`GetPrimaryScreen()` returns the primary screen of the system.
### GetScreens
API: `GetScreens() ([]*Screen, error)`
`GetScreens()` returns information about all screens attached to the system.
This is a brief summary of the exported methods in the provided `App` struct. Do
note that for more detailed functionality or considerations, refer to the actual
Go code or further internal documentation.

67
mkdocs-website/docs/en/API/application_window.md Normal file
View File

@ -0,0 +1,67 @@
### NewWebviewWindow
API: `NewWebviewWindow() *WebviewWindow`
`NewWebviewWindow()` creates a new Webview window with default options, and
returns it.
```go
// Create a new webview window
window := app.NewWebviewWindow()
```
### NewWebviewWindowWithOptions
API:
`NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow`
`NewWebviewWindowWithOptions()` creates a new webview window with custom
options. The newly created window is added to a map of windows managed by the
application.
```go
// Create a new webview window with custom options
window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
Name: "Main",
Title: "My Window",
Width: 800,
Height: 600,
})
```
### OnWindowCreation
API: `OnWindowCreation(callback func(window *WebviewWindow))`
`OnWindowCreation()` registers a callback function to be called when a window is
created.
```go
// Register a callback to be called when a window is created
app.OnWindowCreation(func(window *WebviewWindow) {
// Do something
})
```
### GetWindowByName
API: `GetWindowByName(name string) *WebviewWindow`
`GetWindowByName()` fetches and returns a window with a specific name.
```go
// Get a window by name
window := app.GetWindowByName("Main")
```
### CurrentWindow
API: `CurrentWindow() *WebviewWindow`
`CurrentWindow()` fetches and returns a pointer to the currently active window
in the application. If there is no window, it returns nil.
```go
// Get the current window
window := app.CurrentWindow()
```

4209
mkdocs-website/docs/en/API/fullapi.md
View File

File diff suppressed because it is too large Load Diff

12
mkdocs-website/docs/en/API/window.md
View File

@ -74,7 +74,7 @@ API: `GetScreen() (*Screen, error)`
`GetScreen` method returns the screen on which the window is displayed.
#### SetFrameless
### SetFrameless
API: `SetFrameless(frameless bool) *WebviewWindow`
@ -82,32 +82,32 @@ This function is used to remove the window frame and title bar. It toggles the
framelessness of the window according to the boolean value provided (true for
frameless, false for framed).
#### RegisterContextMenu
### RegisterContextMenu
API: `RegisterContextMenu(name string, menu *Menu)`
This function is used to register a context menu and assigns it the given name.
#### NativeWindowHandle
### NativeWindowHandle
API: `NativeWindowHandle() (uintptr, error)`
This function is used to fetch the platform native window handle for the window.
#### Focus
### Focus
API: `Focus()`
This function is used to focus the window.
#### SetEnabled
### SetEnabled
API: `SetEnabled(enabled bool)`
This function is used to enable/disable the window based on the provided boolean
value.
#### SetAbsolutePosition
### SetAbsolutePosition
API: `SetAbsolutePosition(x int, y int)`

467
mkdocs-website/docs/en/development/changes.md
View File

@ -1,455 +1,22 @@
# Changes for v3
!!! note
This is currently an unsorted brain dump of changes. It will be
organised into a more readable format soon.
This is currently an unsorted brain dump of changes. It will be organised into a more readable format soon.
--8<--
./docs/en/development/changes_events.md
./docs/en/development/changes_window.md
./docs/en/development/changes_systray.md
./docs/en/development/changes_bindings.md
./docs/en/development/changes_dragndrop.md
./docs/en/development/changes_context_menus.md
./docs/en/development/changes_dialogs.md
./docs/en/development/changes_clipboard.md
./docs/en/development/changes_wml.md
./docs/en/development/changes_plugins.md
./docs/en/development/changes_enums.md
./docs/en/development/changes_logging.md
./docs/en/development/changes_misc.md
--8<--
## Options
The application options have been revised since v2.
## Events
In v3, there are 3 types of events:
- Application Events
- Window Events
- Custom Events
### Application Events
Application events are events that are emitted by the application. These events
include native events such as `ApplicationDidFinishLaunching` on macOS.
### Window Events
Window events are events that are emitted by a window. These events include
native events such as `WindowDidBecomeMain` on macOS. Common events are also
defined, so they work cross-platform, e.g. `WindowClosing`.
### Custom Events
Events that the user defines are called `WailsEvents`. This is to differentiate
them from the `Event` object that is used to communicate with the browser.
WailsEvents are now objects that encapsulate all the details of an event. This
includes the event name, the data, and the source of the event.
The data associated with a WailsEvent is now a single value. If multiple values
are required, then a struct can be used.
### Event callbacks and `Emit` function signature
The signatures events callbacks (as used by `On`, `Once` & `OnMultiple`) have
changed. In v2, the callback function received optional data. In v3, the
callback function receives a `WailsEvent` object that contains all data related
to the event.
Similarly, the `Emit` function has changed. Instead of taking a name and
optional data, it now takes a single `WailsEvent` object that it will emit.
### `Off` and `OffAll`
In v2, `Off` and `OffAll` calls would remove events in both JS and Go. Due to
the multi-window nature of v3, this has been changed so that these methods only
apply to the context they are called in. For example, if you call `Off` in a
window, it will only remove events for that window. If you use `Off` in Go, it
will only remove events for Go.
### Hooks
Event Hooks are a new feature in v3. They allow you to hook into the event
system and perform actions when certain events are emitted. For example, you can
hook into the `WindowClosing` event and perform some cleanup before the window
closes. Hooks can be registered at the application level or at the window level
using `RegisterHook`. Application level are for application events. Window level
hooks will only be called for the window they are registered with.
### Logging
Logging in v2 was confusing as both application logs and system (internal) logs
were using the same logger. We have simplified this as follows:
- Internal logs are now handled using the standard Go `slog` logger. This is
configured using the `logger` option in the application options. By default,
this uses the [tint](https://github.com/lmittmann/tint) logger.
- Application logs can now be achieved through the new `log` plugin which
utilises `slog` under the hood. This plugin provides a simple API for logging
to the console. It is available in both Go and JS.
### Developer notes
When emitting an event in Go, it will dispatch the event to local Go listeners
and also each window in the application. When emitting an event in JS, it now
sends the event to the application. This will be processed as if it was emitted
in Go, however the sender ID will be that of the window.
## Window
The Window API has largely remained the same, however the methods are now on an
instance of a window rather than the runtime. Some notable differences are:
- Windows now have a Name that identifies them. This is used to identify the
window when emitting events.
- Windows have even more methods on the that were previously unavailable, such
as `AbsolutePosition` and `ToggleDevTools`.
- Windows can now accept files via native drag and drop. See the Drag and Drop
section for more details.
## ClipBoard
The clipboard API has been simplified. There is now a single `Clipboard` object
that can be used to read and write to the clipboard. The `Clipboard` object is
available in both Go and JS. `SetText()` to set the text and `Text()` to get the
text.
## Bindings
Bindings work in a similar way to v2, by providing a means to bind struct
methods to the frontend. These can be called in the frontend using the binding
wrappers generated by the `wails3 generate bindings` command:
```javascript
// @ts-check
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
import { main } from "./models";
window.go = window.go || {};
window.go.main = {
GreetService: {
/**
* GreetService.Greet
* Greet greets a person
* @param name {string}
* @returns {Promise<string>}
**/
Greet: function (name) {
wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
},
/**
* GreetService.GreetPerson
* GreetPerson greets a person
* @param person {main.Person}
* @returns {Promise<string>}
**/
GreetPerson: function (person) {
wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
},
},
};
```
Bound methods are obfuscated by default, and are identified using uint32 IDs,
calculated using the
[FNV hashing algorithm](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function).
This is to prevent the method name from being exposed in production builds. In
debug mode, the method IDs are logged along with the calculated ID of the method
to aid in debugging. If you wish to add an extra layer of obfuscation, you can
use the `BindAliases` option. This allows you to specify a map of alias IDs to
method IDs. When the frontend calls a method using an ID, the method ID will be
looked up in the alias map first for a match. If it does not find it, it assumes
it's a standard method ID and tries to find the method in the usual way.
Example:
```go
app := application.New(application.Options{
Bind: []any{
&GreetService{},
},
BindAliases: map[uint32]uint32{
1: 1411160069,
2: 4021313248,
},
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
Mac: application.MacOptions{
ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
```
We can now call using this alias in the frontend: `wails.Call(1, "world!")`.
### Insecure calls
If you don't mind your calls being available in plain text in your binary and
have no intention of using [garble](https://github.com/burrowers/garble), then
you can use the insecure `wails.CallByName()` method. This method takes the
fully qualified name of the method to call and the arguments to pass to it.
Example:
```go
wails.CallByName("main.GreetService.Greet", "world!")
```
!!! danger
This is only provided as a convenience method for development. It is not recommended to use this in production.
## Dialogs
Dialogs are now available in JavaScript!
### Windows
Dialog buttons in Windows are not configurable and are constant depending on the
type of dialog. To trigger a callback when a button is pressed, create a button
with the same name as the button you wish to have the callback attached to.
Example: Create a button with the label `Ok` and use `OnClick()` to set the
callback method:
```go
dialog := app.QuestionDialog().
SetTitle("Update").
SetMessage("The cancel button is selected when pressing escape")
ok := dialog.AddButton("Ok")
ok.OnClick(func() {
// Do something
})
no := dialog.AddButton("Cancel")
dialog.SetDefaultButton(ok)
dialog.SetCancelButton(no)
dialog.Show()
```
## Drag and Drop
Native drag and drop can be enabled per-window. Simply set the
`EnableDragAndDrop` window config option to `true` and the window will allow
files to be dragged onto it. When this happens, the `events.FilesDropped` event
will be emitted. The filenames can then be retrieved from the
`WindowEvent.Context()` using the `DroppedFiles()` method. This returns a slice
of strings containing the filenames.
## Context Menus
Context menus are contextual menus that are shown when the user right-clicks on
an element. Creating a context menu is the same as creating a standard menu , by
using `app.NewMenu()`. To make the context menu available to a window, call
`window.RegisterContextMenu(name, menu)`. The name will be the id of the context
menu and used by the frontend.
To indicate that an element has a context menu, add the `data-contextmenu`
attribute to the element. The value of this attribute should be the name of a
context menu previously registered with the window.
It is possible to register a context menu at the application level, making it
available to all windows. This can be done using
`app.RegisterContextMenu(name, menu)`. If a context menu cannot be found at the
window level, the application context menus will be checked. A demo of this can
be found in `v3/examples/contextmenus`.
## Wails Markup Language (WML)
The Wails Markup Language is a simple markup language that allows you to add
functionality to standard HTML elements without the use of Javascript.
The following tags are currently supported:
### `data-wml-event`
This specifies that a Wails event will be emitted when the element is clicked.
The value of the attribute should be the name of the event to emit.
Example:
```html
<button data-wml-event="myevent">Click Me</button>
```
Sometimes you need the user to confirm an action. This can be done by adding the
`data-wml-confirm` attribute to the element. The value of this attribute will be
the message to display to the user.
Example:
```html
<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
Delete All Items
</button>
```
### `data-wml-window`
Any `wails.window` method can be called by adding the `data-wml-window`
attribute to an element. The value of the attribute should be the name of the
method to call. The method name should be in the same case as the method.
```html
<button data-wml-window="Close">Close Window</button>
```
### `data-wml-trigger`
This attribute specifies which javascript event should trigger the action. The
default is `click`.
```html
<button data-wml-event="hover-box" data-wml-trigger="mouseover">
Hover over me!
</button>
```
## Systray
Wails 3 comes with a built-in systray. This is a fully featured systray that has
been designed to be as simple as possible to use. It is possible to set the
icon, tooltip and menu of the systray. It is possible to also "attach" a window
to the systray. Doing this will provide the following functionality:
- Clicking the systray icon with toggle the window visibility
- Right-clicking the systray will open the menu, if there is one
On macOS, if there is no attached window, the systray will use the default
method of displaying the menu (any button). If there is an attached window but
no menu, the systray will toggle the window regardless of the button pressed.
## Plugins
Plugins are a way to extend the functionality of your Wails application.
### Creating a plugin
Plugins are standard Go structure that adhere to the following interface:
```go
type Plugin interface {
Name() string
Init(*application.App) error
Shutdown()
CallableByJS() []string
InjectJS() string
}
```
The `Name()` method returns the name of the plugin. This is used for logging
purposes.
The `Init(*application.App) error` method is called when the plugin is loaded.
The `*application.App` parameter is the application that the plugin is being
loaded into. Any errors will prevent the application from starting.
The `Shutdown()` method is called when the application is shutting down.
The `CallableByJS()` method returns a list of exported functions that can be
called from the frontend. These method names must exactly match the names of the
methods exported by the plugin.
The `InjectJS()` method returns JavaScript that should be injected into all
windows as they are created. This is useful for adding custom JavaScript
functions that complement the plugin.
### Tips
#### Enums
In Go, enums are often defined as a type and a set of constants. For example:
```go
type MyEnum int
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
Due to incompatibility between Go and JavaScript, custom types cannot be used in
this way. The best strategy is to use a type alias for float64:
```go
type MyEnum = float64
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
In Javascript, you can then use the following:
```js
const MyEnum = {
MyEnumOne: 0,
MyEnumTwo: 1,
MyEnumThree: 2,
};
```
- Why use `float64`? Can't we use `int`?
- Because JavaScript doesn't have a concept of `int`. Everything is a
`number`, which translates to `float64` in Go. There are also restrictions
on casting types in Go's reflection package, which means using `int` doesn't
work.
### BackgroundColour
In v2, this was a pointer to an `RGBA` struct. In v3, this is an `RGBA` struct
value.
### WindowIsTranslucent
This flag has been removed. Now there is a `BackgroundType` flag that can be
used to set the type of background the window should have. This flag can be set
to any of the following values:
- `BackgroundTypeSolid` - The window will have a solid background
- `BackgroundTypeTransparent` - The window will have a transparent background
- `BackgroundTypeTranslucent` - The window will have a translucent background
On Windows, if the `BackgroundType` is set to `BackgroundTypeTranslucent`, the
type of translucency can be set using the `BackdropType` flag in the
`WindowsWindow` options. This can be set to any of the following values:
- `Auto` - The window will use an effect determined by the system
- `None` - The window will have no background
- `Mica` - The window will use the Mica effect
- `Acrylic` - The window will use the acrylic effect
- `Tabbed` - The window will use the tabbed effect
## Windows Application Options
### WndProcInterceptor
If this is set, the WndProc will be intercepted and the function will be called.
This allows you to handle Windows messages directly. The function should have
the following signature:
```go
func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnValue uintptr, shouldReturn)
```
The `shouldReturn` value should be set to `true` if the returnValue should be
returned by the main wndProc method. If it is set to `false`, the return value
will be ignored and the message will continue to be processed by the main
wndProc method.
## Hide Window on Close + OnBeforeClose
In v2, there was the `HideWindowOnClose` flag to hide the window when it closed.
There was a logical overlap between this flag and the `OnBeforeClose` callback.
In v3, the `HideWindowOnClose` flag has been removed and the `OnBeforeClose`
callback has been renamed to `ShouldClose`. The `ShouldClose` callback is called
when the user attempts to close a window. If the callback returns `true`, the
window will close. If it returns `false`, the window will not close. This can be
used to hide the window instead of closing it.
## Window Drag
In v2, the `--wails-drag` attribute was used to indicate that an element could
be used to drag the window. In v3, this has been replaced with
`--webkit-app-region` to be more in line with the way other frameworks handle
this. The `--webkit-app-region` attribute can be set to any of the following
values:
- `drag` - The element can be used to drag the window
- `no-drag` - The element cannot be used to drag the window
We would have ideally liked to use `app-region`, however this is not supported
by the `getComputedStyle` call on webkit on macOS.

87
mkdocs-website/docs/en/development/changes_bindings.md Normal file
View File

@ -0,0 +1,87 @@
## Bindings
Bindings work in a similar way to v2, by providing a means to bind struct
methods to the frontend. These can be called in the frontend using the binding
wrappers generated by the `wails3 generate bindings` command:
```javascript
// @ts-check
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
import { main } from "./models";
window.go = window.go || {};
window.go.main = {
GreetService: {
/**
* GreetService.Greet
* Greet greets a person
* @param name {string}
* @returns {Promise<string>}
**/
Greet: function (name) {
wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
},
/**
* GreetService.GreetPerson
* GreetPerson greets a person
* @param person {main.Person}
* @returns {Promise<string>}
**/
GreetPerson: function (person) {
wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
},
},
};
```
Bound methods are obfuscated by default, and are identified using uint32 IDs,
calculated using the
[FNV hashing algorithm](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function).
This is to prevent the method name from being exposed in production builds. In
debug mode, the method IDs are logged along with the calculated ID of the method
to aid in debugging. If you wish to add an extra layer of obfuscation, you can
use the `BindAliases` option. This allows you to specify a map of alias IDs to
method IDs. When the frontend calls a method using an ID, the method ID will be
looked up in the alias map first for a match. If it does not find it, it assumes
it's a standard method ID and tries to find the method in the usual way.
Example:
```go
app := application.New(application.Options{
Bind: []any{
&GreetService{},
},
BindAliases: map[uint32]uint32{
1: 1411160069,
2: 4021313248,
},
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
Mac: application.MacOptions{
ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
```
We can now call using this alias in the frontend: `wails.Call(1, "world!")`.
### Insecure calls
If you don't mind your calls being available in plain text in your binary and
have no intention of using [garble](https://github.com/burrowers/garble), then
you can use the insecure `wails.CallByName()` method. This method takes the
fully qualified name of the method to call and the arguments to pass to it.
Example:
```go
wails.CallByName("main.GreetService.Greet", "world!")
```
!!! danger
This is only provided as a convenience method for development. It is not recommended to use this in production.

6
mkdocs-website/docs/en/development/changes_clipboard.md Normal file
View File

@ -0,0 +1,6 @@
## ClipBoard
The clipboard API has been simplified. There is now a single `Clipboard` object
that can be used to read and write to the clipboard. The `Clipboard` object is
available in both Go and JS. `SetText()` to set the text and `Text()` to get the
text.

17
mkdocs-website/docs/en/development/changes_context_menus.md Normal file
View File

@ -0,0 +1,17 @@
## Context Menus
Context menus are contextual menus that are shown when the user right-clicks on
an element. Creating a context menu is the same as creating a standard menu , by
using `app.NewMenu()`. To make the context menu available to a window, call
`window.RegisterContextMenu(name, menu)`. The name will be the id of the context
menu and used by the frontend.
To indicate that an element has a context menu, add the `data-contextmenu`
attribute to the element. The value of this attribute should be the name of a
context menu previously registered with the window.
It is possible to register a context menu at the application level, making it
available to all windows. This can be done using
`app.RegisterContextMenu(name, menu)`. If a context menu cannot be found at the
window level, the application context menus will be checked. A demo of this can
be found in `v3/examples/contextmenus`.

25
mkdocs-website/docs/en/development/changes_dialogs.md Normal file
View File

@ -0,0 +1,25 @@
## Dialogs
Dialogs are now available in JavaScript!
### Windows
Dialog buttons in Windows are not configurable and are constant depending on the
type of dialog. To trigger a callback when a button is pressed, create a button
with the same name as the button you wish to have the callback attached to.
Example: Create a button with the label `Ok` and use `OnClick()` to set the
callback method:
```go
dialog := app.QuestionDialog().
SetTitle("Update").
SetMessage("The cancel button is selected when pressing escape")
ok := dialog.AddButton("Ok")
ok.OnClick(func() {
// Do something
})
no := dialog.AddButton("Cancel")
dialog.SetDefaultButton(ok)
dialog.SetCancelButton(no)
dialog.Show()
```

8
mkdocs-website/docs/en/development/changes_dragndrop.md Normal file
View File

@ -0,0 +1,8 @@
## Drag and Drop
Native drag and drop can be enabled per-window. Simply set the
`EnableDragAndDrop` window config option to `true` and the window will allow
files to be dragged onto it. When this happens, the `events.FilesDropped` event
will be emitted. The filenames can then be retrieved from the
`WindowEvent.Context()` using the `DroppedFiles()` method. This returns a slice
of strings containing the filenames.

42
mkdocs-website/docs/en/development/changes_enums.md Normal file
View File

@ -0,0 +1,42 @@
#### Enums
In Go, enums are often defined as a type and a set of constants. For example:
```go
type MyEnum int
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
Due to incompatibility between Go and JavaScript, custom types cannot be used in
this way. The best strategy is to use a type alias for float64:
```go
type MyEnum = float64
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
In Javascript, you can then use the following:
```js
const MyEnum = {
MyEnumOne: 0,
MyEnumTwo: 1,
MyEnumThree: 2,
};
```
- Why use `float64`? Can't we use `int`?
- Because JavaScript doesn't have a concept of `int`. Everything is a
`number`, which translates to `float64` in Go. There are also restrictions
on casting types in Go's reflection package, which means using `int` doesn't
work.

62
mkdocs-website/docs/en/development/changes_events.md Normal file
View File

@ -0,0 +1,62 @@
## Events
In v3, there are 3 types of events:
- Application Events
- Window Events
- Custom Events
### Application Events
Application events are events that are emitted by the application. These events
include native events such as `ApplicationDidFinishLaunching` on macOS.
### Window Events
Window events are events that are emitted by a window. These events include
native events such as `WindowDidBecomeMain` on macOS. Common events are also
defined, so they work cross-platform, e.g. `WindowClosing`.
### Custom Events
Events that the user defines are called `WailsEvents`. This is to differentiate
them from the `Event` object that is used to communicate with the browser.
WailsEvents are now objects that encapsulate all the details of an event. This
includes the event name, the data, and the source of the event.
The data associated with a WailsEvent is now a single value. If multiple values
are required, then a struct can be used.
### Event callbacks and `Emit` function signature
The signatures events callbacks (as used by `On`, `Once` & `OnMultiple`) have
changed. In v2, the callback function received optional data. In v3, the
callback function receives a `WailsEvent` object that contains all data related
to the event.
Similarly, the `Emit` function has changed. Instead of taking a name and
optional data, it now takes a single `WailsEvent` object that it will emit.
### `Off` and `OffAll`
In v2, `Off` and `OffAll` calls would remove events in both JS and Go. Due to
the multi-window nature of v3, this has been changed so that these methods only
apply to the context they are called in. For example, if you call `Off` in a
window, it will only remove events for that window. If you use `Off` in Go, it
will only remove events for Go.
### Hooks
Event Hooks are a new feature in v3. They allow you to hook into the event
system and perform actions when certain events are emitted. For example, you can
hook into the `WindowClosing` event and perform some cleanup before the window
closes. Hooks can be registered at the application level or at the window level
using `RegisterHook`. Application level are for application events. Window level
hooks will only be called for the window they are registered with.
### Developer notes
When emitting an event in Go, it will dispatch the event to local Go listeners
and also each window in the application. When emitting an event in JS, it now
sends the event to the application. This will be processed as if it was emitted
in Go, however the sender ID will be that of the window.

11
mkdocs-website/docs/en/development/changes_logging.md Normal file
View File

@ -0,0 +1,11 @@
### Logging
Logging in v2 was confusing as both application logs and system (internal) logs
were using the same logger. We have simplified this as follows:
- Internal logs are now handled using the standard Go `slog` logger. This is
configured using the `logger` option in the application options. By default,
this uses the [tint](https://github.com/lmittmann/tint) logger.
- Application logs can now be achieved through the new `log` plugin which
utilises `slog` under the hood. This plugin provides a simple API for logging
to the console. It is available in both Go and JS.

42
mkdocs-website/docs/en/development/changes_misc.md Normal file
View File

@ -0,0 +1,42 @@
### Misc
## Windows Application Options
### WndProcInterceptor
If this is set, the WndProc will be intercepted and the function will be called.
This allows you to handle Windows messages directly. The function should have
the following signature:
```go
func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnValue uintptr, shouldReturn)
```
The `shouldReturn` value should be set to `true` if the returnValue should be
returned by the main wndProc method. If it is set to `false`, the return value
will be ignored and the message will continue to be processed by the main
wndProc method.
## Hide Window on Close + OnBeforeClose
In v2, there was the `HideWindowOnClose` flag to hide the window when it closed.
There was a logical overlap between this flag and the `OnBeforeClose` callback.
In v3, the `HideWindowOnClose` flag has been removed and the `OnBeforeClose`
callback has been renamed to `ShouldClose`. The `ShouldClose` callback is called
when the user attempts to close a window. If the callback returns `true`, the
window will close. If it returns `false`, the window will not close. This can be
used to hide the window instead of closing it.
## Window Drag
In v2, the `--wails-drag` attribute was used to indicate that an element could
be used to drag the window. In v3, this has been replaced with
`--webkit-app-region` to be more in line with the way other frameworks handle
this. The `--webkit-app-region` attribute can be set to any of the following
values:
- `drag` - The element can be used to drag the window
- `no-drag` - The element cannot be used to drag the window
We would have ideally liked to use `app-region`, however this is not supported
by the `getComputedStyle` call on webkit on macOS.

34
mkdocs-website/docs/en/development/changes_plugins.md Normal file
View File

@ -0,0 +1,34 @@
## Plugins
Plugins are a way to extend the functionality of your Wails application.
### Creating a plugin
Plugins are standard Go structure that adhere to the following interface:
```go
type Plugin interface {
Name() string
Init(*application.App) error
Shutdown()
CallableByJS() []string
InjectJS() string
}
```
The `Name()` method returns the name of the plugin. This is used for logging
purposes.
The `Init(*application.App) error` method is called when the plugin is loaded.
The `*application.App` parameter is the application that the plugin is being
loaded into. Any errors will prevent the application from starting.
The `Shutdown()` method is called when the application is shutting down.
The `CallableByJS()` method returns a list of exported functions that can be
called from the frontend. These method names must exactly match the names of the
methods exported by the plugin.
The `InjectJS()` method returns JavaScript that should be injected into all
windows as they are created. This is useful for adding custom JavaScript
functions that complement the plugin.

13
mkdocs-website/docs/en/development/changes_systray.md Normal file
View File

@ -0,0 +1,13 @@
## Systray
Wails 3 comes with a built-in systray. This is a fully featured systray that has
been designed to be as simple as possible to use. It is possible to set the
icon, tooltip and menu of the systray. It is possible to also "attach" a window
to the systray. Doing this will provide the following functionality:
- Clicking the systray icon with toggle the window visibility
- Right-clicking the systray will open the menu, if there is one
On macOS, if there is no attached window, the systray will use the default
method of displaying the menu (any button). If there is an attached window but
no menu, the systray will toggle the window regardless of the button pressed.

36
mkdocs-website/docs/en/development/changes_window.md Normal file
View File

@ -0,0 +1,36 @@
## Window
The Window API has largely remained the same, however the methods are now on an
instance of a window rather than the runtime. Some notable differences are:
- Windows now have a Name that identifies them. This is used to identify the
window when emitting events.
- Windows have even more methods on the that were previously unavailable, such
as `AbsolutePosition` and `ToggleDevTools`.
- Windows can now accept files via native drag and drop. See the Drag and Drop
section for more details.
### BackgroundColour
In v2, this was a pointer to an `RGBA` struct. In v3, this is an `RGBA` struct
value.
### WindowIsTranslucent
This flag has been removed. Now there is a `BackgroundType` flag that can be
used to set the type of background the window should have. This flag can be set
to any of the following values:
- `BackgroundTypeSolid` - The window will have a solid background
- `BackgroundTypeTransparent` - The window will have a transparent background
- `BackgroundTypeTranslucent` - The window will have a translucent background
On Windows, if the `BackgroundType` is set to `BackgroundTypeTranslucent`, the
type of translucency can be set using the `BackdropType` flag in the
`WindowsWindow` options. This can be set to any of the following values:
- `Auto` - The window will use an effect determined by the system
- `None` - The window will have no background
- `Mica` - The window will use the Mica effect
- `Acrylic` - The window will use the acrylic effect
- `Tabbed` - The window will use the tabbed effect

50
mkdocs-website/docs/en/development/changes_wml.md Normal file
View File

@ -0,0 +1,50 @@
## Wails Markup Language (WML)
The Wails Markup Language is a simple markup language that allows you to add
functionality to standard HTML elements without the use of Javascript.
The following tags are currently supported:
### `data-wml-event`
This specifies that a Wails event will be emitted when the element is clicked.
The value of the attribute should be the name of the event to emit.
Example:
```html
<button data-wml-event="myevent">Click Me</button>
```
Sometimes you need the user to confirm an action. This can be done by adding the
`data-wml-confirm` attribute to the element. The value of this attribute will be
the message to display to the user.
Example:
```html
<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
Delete All Items
</button>
```
### `data-wml-window`
Any `wails.window` method can be called by adding the `data-wml-window`
attribute to an element. The value of the attribute should be the name of the
method to call. The method name should be in the same case as the method.
```html
<button data-wml-window="Close">Close Window</button>
```
### `data-wml-trigger`
This attribute specifies which javascript event should trigger the action. The
default is `click`.
```html
<button data-wml-event="hover-box" data-wml-trigger="mouseover">
Hover over me!
</button>
```

335
mkdocs-website/docs/zh/API/application.md
View File

@ -1,335 +0,0 @@
# 应用程序
应用程序 API 用于使用 Wails 框架创建应用程序。
### New
API：`New(appOptions Options) *App`
`New(appOptions Options)` 使用给定的应用程序选项创建一个新的应用程序。它对未指定
的选项应用默认值，将其与提供的选项合并，然后初始化并返回应用程序的实例。
如果在初始化过程中出现错误，应用程序将停止，并显示提供的错误消息。
需要注意的是，如果全局应用程序实例已经存在，将返回该实例，而不是创建新的实例。
```go title="main.go" hl_lines="6-9"
package main
import "github.com/wailsapp/wails/v3/pkg/application"
func main() {
app := application.New(application.Options{
Name: "WebviewWindow Demo",
// 其他选项
})
// 其余的应用程序逻辑
}
```
### Get
`Get()` 返回全局应用程序实例。在代码的不同部分需要访问应用程序时非常有用。
```go
// 获取应用程序实例
app := application.Get()
```
### Capabilities
API：`Capabilities() capabilities.Capabilities`
`Capabilities()` 返回应用程序当前具有的功能的映射。这些功能可以是操作系统提供的
不同功能，如 webview 功能。
```go
// 获取应用程序的功能
capabilities := app.Capabilities()
if capabilities.HasNativeDrag {
// 做一些事情
}
```
### GetPID
API：`GetPID() int`
`GetPID()` 返回应用程序的进程 ID。
```go
pid := app.GetPID()
```
### Run
API：`Run() error`
`Run()` 启动应用程序及其组件的执行。
```go
app := application.New(application.Options{
// 选项
})
// 运行应用程序
err := application.Run()
if err != nil {
// 处理错误
}
```
### Quit
API：`Quit()`
`Quit()` 通过销毁窗口和可能的其他组件退出应用程序。
```go
// 退出应用程序
app.Quit()
```
### IsDarkMode
API：`IsDarkMode() bool`
`IsDarkMode()` 检查应用程序是否在暗模式下运行。它返回一个布尔值，指示是否启用了
暗模式。
```go
// 检查是否启用了暗模式
if app.IsDarkMode() {
// 做一些事情
}
```
### Hide
API：`Hide()`
`Hide()` 隐藏应用程序窗口。
```go
// 隐藏应用程序窗口
app.Hide()
```
### Show
API：`Show()`
`Show()` 显示应用程序窗口。
```go
// 显示应用程序窗口
app.Show()
```
### NewWebviewWindow
API：`NewWebviewWindow() *WebviewWindow`
`NewWebviewWindow()` 使用默认选项创建一个新的 Webview 窗口，并返回它。
```go
// 创建一个新的 Webview 窗口
window := app.NewWebviewWindow()
```
### NewWebviewWindowWithOptions
API：`NewWebviewWindowWithOptions(windowOptions WebviewWindowOptions) *WebviewWindow`
`NewWebviewWindowWithOptions()` 使用自定义选项创建一个新的 Webview 窗口。新创建
的窗口将添加到应用程序管理的窗口映射中。
```go
// 使用自定义选项创建一个新的 Webview 窗口
window := app.NewWebviewWindowWithOptions(WebviewWindowOptions{
Name: "Main",
Title: "My Window",
Width: 800,
Height: 600,
})
```
### OnWindowCreation
API：`OnWindowCreation(callback func(window *WebviewWindow))`
`OnWindowCreation()` 注册一个回调函数，当创建窗口时调用该函数。
```go
// 注册一个回调函数，当创建窗口时调用该函数
app.OnWindowCreation(func(window *WebviewWindow) {
// 做一些事情
})
```
### GetWindowByName
API：`GetWindowByName(name string) *WebviewWindow`
`GetWindowByName()` 获取并返回具有特定名称的窗口。
```go
// 通过名称获取窗口
window := app.GetWindowByName("Main")
```
### CurrentWindow
API：`CurrentWindow() *WebviewWindow`
`CurrentWindow()` 获取并返回应用程序中当前活动窗口的指针。如果没有窗口，则返回
nil。
```go
// 获取当前窗口
window := app.CurrentWindow()
```
### RegisterContextMenu
API：`RegisterContextMenu(name string, menu *Menu)`
`RegisterContextMenu()` 注册具有给定名称的上下文菜单。稍后可以在应用程序中使用该
菜单。
```go
// 创建一个新的菜单
ctxmenu := app.NewMenu()
// 将菜单注册为上下文菜单
app.RegisterContextMenu("MyContextMenu", ctxmenu)
```
### SetMenu
API：`SetMenu(menu *Menu)`
`SetMenu()` 设置应用程序的菜单。在 Mac 上，这将是全局菜单。对于 Windows 和
Linux，这将是任何新窗口的默认菜单。
```go
// 创建一个新的菜单
menu := app.NewMenu()
// 设置应用程序的菜单
app.SetMenu(menu)
```
### ShowAboutDialog
API：`ShowAboutDialog()`
`ShowAboutDialog()` 显示一个 "关于" 对话框。可以显示应用程序的名称、描述和图标。
```go
// 显示关于对话框
app.ShowAboutDialog()
```
### Info
API：`InfoDialog()`
`InfoDialog()` 创建并返回一个具有 `InfoDialogType` 的 `MessageDialog` 的新实例。
此对话框通常用于向用户显示信息消息。
### Question
API：`QuestionDialog()`
`QuestionDialog()` 创建并返回一个具有 `QuestionDialogType` 的 `MessageDialog` 的
新实例。此对话框通常用于向用户提问并期望回应。
### Warning
API：`WarningDialog()`
`WarningDialog()` 创建并返回一个具有 `WarningDialogType` 的 `MessageDialog` 的新
实例。如其名称所示，此对话框主要用于向用户显示警告消息。
### Error
API：`ErrorDialog()`
`ErrorDialog()` 创建并返回一个具有 `ErrorDialogType` 的 `MessageDialog` 的新实
例。此对话框设计用于在需要向用户显示错误消息时使用。
### OpenFile
API：`OpenFileDialog()`
`OpenFileDialog()` 创建并返回一个新的 `OpenFileDialogStruct`。此对话框提示用户从
其文件系统中选择一个或多个文件。
### SaveFile
API：`SaveFileDialog()`
`SaveFileDialog()` 创建并返回一个新的 `SaveFileDialogStruct`。此对话框提示用户选
择其文件系统上的位置以保存文件。
### OpenDirectory
API：`OpenDirectoryDialog()`
`OpenDirectoryDialog()` 创建并返回一个具有 `OpenDirectoryDialogType` 的
`MessageDialog` 的新实例。此对话框使用户能够从其文件系统中选择目录。
### On
API：`On(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`On()` 注册特定应用程序事件的事件侦听器。提供的回调函数将在相应事件发生时触发。
该函数返回一个可调用的函数，用于删除侦听器。
### RegisterHook
API：`RegisterHook(eventType events.ApplicationEventType, callback func(event *Event)) func()`
`RegisterHook()` 注册要在特定事件期间作为钩子运行的回调函数。这些钩子在使用
`On()` 附加的侦听器之前运行。该函数返回一个可调用的函数，用于删除钩子。
### GetPrimaryScreen
API：`GetPrimaryScreen() (*Screen, error)`
`GetPrimaryScreen()` 返回系统的主屏幕。
### GetScreens
API：`GetScreens() ([]*Screen, error)`
`GetScreens()` 返回有关连接到系统的所有屏幕的信息。
这是提供的 `App` 结构中导出的方法的简要摘要。请注意，有关更详细的功能或注意事
项，请参考实际的 Go 代码或进一步的内部文档。
## Options
```go title="application_options.go"
--8<--
../v3/pkg/application/options_application.go
--8<--
```
### Windows 选项
```go title="application_options_windows.go"
--8<--
../v3/pkg/application/options_application_win.go
--8<--
```
### Mac 选项
```go title="options_application_mac.go"
--8<--
../v3/pkg/application/options_application_mac.go
--8<--
```

45
mkdocs-website/docs/zh/API/mainthread.md
View File

@ -1,45 +0,0 @@
# 主线程函数
这些方法是在主线程上运行代码的实用函数。当您想要在UI线程上运行自定义代码时，这是
必需的。
### InvokeSync
API: `InvokeSync(fn func())`
此函数以同步方式运行传入的函数（`fn`）。它使用一个`WaitGroup`（`wg`）确保主线程
在`fn`函数完成之前等待，然后才继续执行。如果在`fn`内部发生恐慌，它将传递给应用程
序选项中定义的处理程序函数`PanicHandler`。
### InvokeSyncWithResult
API: `InvokeSyncWithResult[T any](fn func() T) (res T)`
此函数与`InvokeSync(fn func())`类似，但它返回一个结果。可用于调用具有单个返回值
的任何函数。
### InvokeSyncWithError
API: `InvokeSyncWithError(fn func() error) (err error)`
此函数同步运行`fn`并返回`fn`产生的任何错误。请注意，如果在`fn`执行期间发生恐慌，
此函数将从恢复。
### InvokeSyncWithResultAndError
API:
`InvokeSyncWithResultAndError[T any](fn func() (T, error)) (res T, err error)`
此函数同步运行`fn`并返回类型为`T`的结果和一个错误。
### InvokeAsync
API: `InvokeAsync(fn func())`
此函数以异步方式运行`fn`。它在主线程上运行给定的函数。如果在`fn`内部发生恐慌，它
将传递给应用程序选项中定义的处理程序函数`PanicHandler`。
---
注意：这些函数将阻塞执行，直到`fn`完成。确保`fn`不会阻塞至关重要。如果需要运行阻
塞函数，请改用`InvokeAsync`。

66
mkdocs-website/docs/zh/API/menu.md
View File

@ -1,66 +0,0 @@
# 菜单
可以创建菜单并添加到应用程序中。它们可以用于创建上下文菜单、系统托盘菜单和应用程
序菜单。
要创建一个新菜单，请调用：
```go
// 创建一个新菜单
menu := app.NewMenu()
```
然后，`Menu` 类型上可用以下操作：
### 添加
API：`Add(label string) *MenuItem`
此方法以 `string` 类型的 `label` 作为输入，并将具有给定标签的新 `MenuItem` 添加
到菜单中。它返回添加的 `MenuItem`。
### 添加分隔符
API：`AddSeparator()`
此方法将一个新的分隔符 `MenuItem` 添加到菜单中。
### 添加复选框
API：`AddCheckbox(label string, enabled bool) *MenuItem`
此方法以 `string` 类型的 `label` 和 `bool` 类型的 `enabled` 作为输入，并将具有给
定标签和启用状态的新复选框 `MenuItem` 添加到菜单中。它返回添加的 `MenuItem`。
### 添加单选按钮
API：`AddRadio(label string, enabled bool) *MenuItem`
此方法以 `string` 类型的 `label` 和 `bool` 类型的 `enabled` 作为输入，并将具有给
定标签和启用状态的新单选按钮 `MenuItem` 添加到菜单中。它返回添加的 `MenuItem`。
### 更新
API：`Update()`
此方法处理任何单选按钮组，并在菜单未初始化时更新菜单。
### 添加子菜单
API：`AddSubmenu(s string) *Menu`
此方法以 `string` 类型的 `s` 作为输入，并将具有给定标签的新子菜单 `MenuItem` 添
加到菜单中。它返回添加的子菜单。
### 添加角色
API：`AddRole(role Role) *Menu`
此方法以 `Role` 类型的 `role` 作为输入，如果不为 `nil`，则将其添加到菜单中，并返
回 `Menu`。
### 设置标签
API：`SetLabel(label string)`
此方法设置 `Menu` 的 `label`。

103
mkdocs-website/docs/zh/API/systray.md
View File

@ -1,103 +0,0 @@
# 系统托盘
系统托盘位于桌面环境的通知区域，可以包含当前运行应用程序的图标和特定系统通知。
您可以通过调用 `app.NewSystemTray()` 来创建一个系统托盘：
```go
// 创建一个新的系统托盘
tray := app.NewSystemTray()
```
`SystemTray` 类型上提供了以下方法：
### SetLabel
API：`SetLabel(label string)`
`SetLabel` 方法设置托盘的标签。
### Label
API：`Label() string`
`Label` 方法获取托盘的标签。
### PositionWindow
API：`PositionWindow(*WebviewWindow, offset int) error`
`PositionWindow` 方法调用了 `AttachWindow` 和 `WindowOffset` 方法。
### SetIcon
API：`SetIcon(icon []byte) *SystemTray`
`SetIcon` 方法设置系统托盘的图标。
### SetDarkModeIcon
API：`SetDarkModeIcon(icon []byte) *SystemTray`
`SetDarkModeIcon` 方法设置暗黑模式下系统托盘的图标。
### SetMenu
API：`SetMenu(menu *Menu) *SystemTray`
`SetMenu` 方法设置系统托盘的菜单。
### Destroy
API：`Destroy()`
`Destroy` 方法销毁系统托盘实例。
### OnClick
API：`OnClick(handler func()) *SystemTray`
`OnClick` 方法设置点击托盘图标时执行的函数。
### OnRightClick
API：`OnRightClick(handler func()) *SystemTray`
`OnRightClick` 方法设置右键点击托盘图标时执行的函数。
### OnDoubleClick
API：`OnDoubleClick(handler func()) *SystemTray`
`OnDoubleClick` 方法设置双击托盘图标时执行的函数。
### OnRightDoubleClick
API：`OnRightDoubleClick(handler func()) *SystemTray`
`OnRightDoubleClick` 方法设置右键双击托盘图标时执行的函数。
### AttachWindow
API：`AttachWindow(window *WebviewWindow) *SystemTray`
`AttachWindow` 方法将窗口附加到系统托盘。当点击系统托盘图标时，窗口将显示出来。
### WindowOffset
API：`WindowOffset(offset int) *SystemTray`
`WindowOffset` 方法设置系统托盘与窗口之间的像素间隔。
### WindowDebounce
API：`WindowDebounce(debounce time.Duration) *SystemTray`
`WindowDebounce` 方法设置防抖时间。在 Windows 上，它用于指定在响应通知图标上的鼠
标松开事件之前等待多长时间。
### OpenMenu
API：`OpenMenu()`
`OpenMenu` 方法打开与系统托盘关联的菜单。

106
mkdocs-website/docs/zh/API/window.md
View File

@ -1,106 +0,0 @@
# 窗口
要创建一个窗口，可以使
用[Application.NewWebviewWindow](application.md#newwebviewwindow)或[Application.NewWebviewWindowWithOptions](application.md#newwebviewwindowwithoptions)。
前者创建一个具有默认选项的窗口，而后者允许您指定自定义选项。
这些方法可在返回的WebviewWindow对象上调用：
### SetTitle
API: `SetTitle(title string) *WebviewWindow`
此方法将窗口标题更新为提供的字符串。它返回WebviewWindow对象，允许进行方法链接。
### Name
API: `Name() string`
此函数返回WebviewWindow的名称。
### SetSize
API: `SetSize(width, height int) *WebviewWindow`
此方法将WebviewWindow的大小设置为提供的宽度和高度参数。如果提供的尺寸超过约束条
件，它们将被相应调整。
### SetAlwaysOnTop
API: `SetAlwaysOnTop(b bool) *WebviewWindow`
此函数根据提供的布尔标志设置窗口始终置顶。
### Show
API: `Show() *WebviewWindow`
`Show`方法用于使窗口可见。如果窗口未运行，它首先调用`run`方法启动窗口，然后使其
可见。
### Hide
API: `Hide() *WebviewWindow`
`Hide`方法用于隐藏窗口。它将窗口的隐藏状态设置为true，并触发窗口隐藏事件。
### SetURL
API: `SetURL(s string) *WebviewWindow`
`SetURL`方法用于将窗口的URL设置为给定的URL字符串。
### SetZoom
API: `SetZoom(magnification float64) *WebviewWindow`
`SetZoom`方法将窗口内容的缩放级别设置为提供的放大倍数。
### GetZoom
API: `GetZoom() float64`
`GetZoom`函数返回窗口内容的当前缩放级别。
### GetScreen
API: `GetScreen() (*Screen, error)`
`GetScreen`方法返回窗口所显示的屏幕。
#### SetFrameless
API: `SetFrameless(frameless bool) *WebviewWindow`
此函数用于移除窗口边框和标题栏。它根据提供的布尔值（true表示无边框，false表示有
边框）切换窗口的无边框状态。
#### RegisterContextMenu
API: `RegisterContextMenu(name string, menu *Menu)`
此函数用于注册上下文菜单并为其指定给定的名称。
#### NativeWindowHandle
API: `NativeWindowHandle() (uintptr, error)`
此函数用于获取窗口的平台本机窗口句柄。
#### Focus
API: `Focus()`
此函数用于将焦点设置到窗口。
#### SetEnabled
API: `SetEnabled(enabled bool)`
此函数用于根据提供的布尔值启用/禁用窗口。
#### SetAbsolutePosition
API: `SetAbsolutePosition(x int, y int)`
此函数设置窗口在屏幕上的绝对位置。

44
mkdocs-website/docs/zh/changelog.md
View File

@ -1,44 +0,0 @@
# 更新日志
<!--
此项目的所有重要更改将在此文件中记录。
格式基于[保持一个更改日志](https://keepachangelog.com/en/1.0.0/)，
并且该项目遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。
- `Added` 用于新增功能。
- `Changed` 用于现有功能的更改。
- `Deprecated` 用于即将移除的功能。
- `Removed` 用于已移除的功能。
- `Fixed` 用于修复错误。
- `Security` 用于安全漏洞。
-->
## [未发布]
### Added
- [darwin] 添加Event ApplicationShouldHandleReopen以处理单击dock图标的功能
@5aaee9 in [#2991](https://github.com/wailsapp/wails/pull/2991)
- [darwin] 添加getPrimaryScreen/getScreens的实现 @tmclane in
[#2618](https://github.com/wailsapp/wails/pull/2618)
### Fixed
- 修复Doctor apt软件包验证问题 [Atterpac](https://github.com/Atterpac) in
[#2972](https://github.com/wailsapp/wails/pull/2972)。
- 修复应用程序在退出时冻结的问题 (Darwin) @5aaee9 in
[#2982](https://github.com/wailsapp/wails/pull/2982)
- 修复Windows上示例的背景颜色问题 [mmgvh](https://github.com/mmghv) in
[#2750](https://github.com/wailsapp/wails/pull/2750)。
- 修复默认上下文菜单问题 [mmgvh](https://github.com/mmghv) in
[#2753](https://github.com/wailsapp/wails/pull/2753)。
### Changed
### Removed
### Deprecated
### Security

402
mkdocs-website/docs/zh/development/changes.md
View File

@ -1,402 +0,0 @@
# v3的更改
!!! note这是当前的无序更改脑升级。很快它将组织成一个更易读的格式。
## 选项
自v2以来，应用程序选项已经进行了修订。
## 事件
在v3中，有3种类型的事件：
- 应用程序事件
- 窗口事件
- 自定义事件
### 应用程序事件
应用程序事件是由应用程序发出的事件。这些事件包括macOS上
的`ApplicationDidFinishLaunching`等本机事件。
### 窗口事件
窗口事件是由窗口发出的事件。这些事件包括macOS上的`WindowDidBecomeMain`等本机事
件。还定义了常见事件，以便它们在跨平台上工作，例如`WindowClosing`。
### 自定义事件
用户定义的事件称为`WailsEvents`。这是为了将它们与用于与浏览器通信的`Event`对象区
分开来。WailsEvents现在是封装事件的对象。这包括事件名称，数据和事件的源。
与WailsEvent关联的数据现在是单个值。如果需要多个值，则可以使用struct。
### 事件回调和`Emit`函数签名
事件回调的签名（由`On`，`Once`和`OnMultiple`使用）已更改。在v2中，回调函数接收可
选数据。在v3中，回调函数接收包含与事件相关的所有数据的`WailsEvent`对象。
类似地，`Emit`函数已更改。它现在不再接受名称和可选数据，而是接受一
个`WailsEvent`对象，它将发出该对象。
### `Off`和`OffAll`
在v2中，`Off`和`OffAll`调用将删除JS和Go中的事件。由于v3具有多窗口的特性，因此已
更改为这些方法仅适用于调用它们的上下文。例如，如果你在一个窗口中调用`Off`，它仅
会删除该窗口的事件。如果你在Go中使用`Off`，它只会删除Go的事件。
### Hooks
事件钩子是v3中的新功能。它们允许您钩入事件系统，并在发出某些事件时执行操作。例
如，您可以钩入`WindowClosing`事件，在窗口关闭之前执行一些清理操作。钩子可以在应
用程序级别或窗口级别使用`RegisterHook`进行注册。应用程序级别适用于应用程序事件。
仅当窗口级别钩子与其注册的窗口一起调用。
### 日志记录
在v2中，日志记录会混淆，因为应用程序日志和系统（内部）日志都使用相同的记录器。我
们已经对此进行了简化：
- 内部日志现在使用标准的Go `slog`记录器处理。这是通过应用程序选项中的`logger`选
项进行配置的。默认情况下，这使用[tint](https://github.com/lmittmann/tint)记录
器。
- 现在可以通过新的`log`插件进行应用程序日志记录，它在底层使用`slog`。此插件提供
了一个简单的用于记录到控制台的API。它在Go和JS中都可用。
### 开发人员注意事项
在Go中发出事件时，它会将事件分派到本地的Go侦听器以及应用程序中的每个窗口。在JS中
发出事件时，它现在会将事件发送到应用程序。这将被处理，就好像它是在Go中发出的，但
是发送者ID将是窗口的ID。
## 窗口
Window API在很大程度上保持不变，但方法现在是在窗口实例而不是运行时上。一些值得注
意的变化是：
- 窗口现在具有标识它们的名称。用于在发出事件时标识窗口。
- 窗口上现在有更多以前不可用的方法，例如`AbsolutePosition`和`ToggleDevTools`。
- 窗口现在可以通过本机拖放接受文件。有关详细信息，请参阅拖放部分。
## 剪切板
剪贴板API已经简化。现在有一个单独的`Clipboard`对象，可以用于读取和写入剪贴
板。`Clipboard`对象在Go和JS中都可用。`SetText()`用于设置文本，`Text()`用于获取文
本。
## 绑定
绑定的工作方式与v2类似，通过提供一种将结构方法绑定到前端的方式。这些可以在前端使
用由`wails3 generate bindings`命令生成的绑定包装器来调用：
```javascript
// @ts-check
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
import { main } from "./models";
window.go = window.go || {};
window.go.main = {
GreetService: {
/**
* GreetService.Greet
* Greet greets a person
* @param name {string}
* @returns {Promise<string>}
**/
Greet: function (name) {
wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
},
/**
* GreetService.GreetPerson
* GreetPerson greets a person
* @param person {main.Person}
* @returns {Promise<string>}
**/
GreetPerson: function (person) {
wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
},
},
};
```
默认情况下，绑定的方法是混淆的，并使用uint32 ID进行标识，该ID是使
用[FNV哈希算法](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function)计
算的。这是为了防止方法名称在生产构建中被暴露出来。在调试模式下，方法ID与计算的方
法ID一起记录，以帮助调试。如果您希望增加额外的混淆层，可以使用`BindAliases`选
项。这允许您指定别名ID与方法ID的映射。当前端使用ID调用方法时，方法ID将首先在别名
映射中查找匹配项。如果找不到，它将假定是标准方法ID，并尝试以通常的方式查找方法。
示例：
```go
app := application.New(application.Options{
Bind: []any{
&GreetService{},
},
BindAliases: map[uint32]uint32{
1: 1411160069,
2: 4021313248,
},
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
Mac: application.MacOptions{
ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
```
现在我们可以使用此别名在前端调用：`wails.Call(1, "world!")`。
### 不安全调用
如果您不介意在二进制文件中以明文形式提供调用，并且不打算使
用[garble](https://github.com/burrowers/garble)，那么可以使用不安全
的`wails.CallByName()`方法。此方法接受要调用的方法的完全限定名称和要传递给它的参
数。示例：
```go
wails.CallByName("main.GreetService.Greet", "world!")
```
!!! danger
这仅作为开发的便利方法提供。不建议在生产中使用此方法。
## 对话框
对话框现在在JavaScript中可用！
### Windows
Windows中的对话框按钮是不可配置的，根据对话框的类型是恒定的。要在按下按钮时触发
回调，请创建一个具有与您希望附加回调的按钮相同名称的按钮。示例：创建一个标签为“
确定”的按钮，并使用`OnClick()`方法设置回调方法：
```go
dialog := app.QuestionDialog().
SetTitle("Update").
SetMessage("The cancel button is selected when pressing escape")
ok := dialog.AddButton("Ok")
ok.OnClick(func() {
// Do something
})
no := dialog.AddButton("Cancel")
dialog.SetDefaultButton(ok)
dialog.SetCancelButton(no)
dialog.Show()
```
## 拖放
可以按窗口启用本机拖放。只需将`EnableDragAndDrop`窗口配置选项设置为`true`，窗口
将允许将文件拖放到其上。当这种情况发生时，将发出`events.FilesDropped`事件。然后
可以使用`WindowEvent.Context()`中的`DroppedFiles()`方法检索文件名。这将返回一个
包含文件名的字符串切片。
## 上下文菜单
上下文菜单是当用户右键单击元素时显示的上下文菜单。创建上下文菜单与创建标准菜单相
同，使用`app.NewMenu()`。要使上下文菜单对窗口可用，请调
用`window.RegisterContextMenu(name, menu)`。名称将是上下文菜单的ID，并由前端使
用。
要指示元素具有上下文菜单，请将`data-contextmenu`属性添加到元素。此属性的值应为先
前在窗口中注册的上下文菜单的名称。
可以在应用程序级别注册上下文菜单，使其对所有窗口可用。可以使
用`app.RegisterContextMenu(name, menu)`完成此操作。如果在窗口级别找不到上下文菜
单，则将检查应用程序上下文菜单。`v3/examples/contextmenus`中可以找到此演示。
## Wails标记语言（WML）
Wails标记语言是一种简单的标记语言，允许您在没有JavaScript的情况下向标准HTML元素
添加功能。
当前支持以下标签：
### `data-wml-event`
这指定单击元素时将发出Wails事件。属性的值应为要发出的事件的名称。
示例：
```html
<button data-wml-event="myevent">Click Me</button>
```
有时您需要用户确认操作。可以通过向元素添加`data-wml-confirm`属性来完成。此属性的
值将是要显示给用户的消息。
示例：
```html
<button data-wml-event="delete-all-items" data-wml-confirm="Are you sure?">
Delete All Items
</button>
```
### `data-wml-window`
可以通过将`data-wml-window`属性添加到元素中来调用任何`wails.window`方法。属性的
值应为要调用的方法的名称。方法名称应与导出的方法的名称完全匹配。
```html
<button data-wml-window="Close">Close Window</button>
```
### `data-wml-trigger`
此属性指定应触发操作的javascript事件。默认为`click`。
```html
<button data-wml-event="hover-box" data-wml-trigger="mouseover">
Hover over me!
</button>
```
## 系统托盘
Wails 3附带了一个内置的系统托盘。这是一个完全功能的系统托盘，旨在尽可能简单地使
用。可以设置托盘的图标、工具提示和菜单。还可以“附加”窗口到系统托盘。这样做将提供
以下功能：
- 单击托盘图标会切换窗口可见性
- 右键单击托盘将打开菜单（如果有）
在macOS上，如果没有附加的窗口，则托盘将使用显示菜单的默认方法（任何按钮）。如果
有附加的窗口但没有菜单，则托盘将切换窗口，而不管按下的按钮如何。
## 插件
插件是扩展Wails应用程序功能的一种方式。
### 创建插件
插件是符合以下接口的标准Go结构：
```go
type Plugin interface {
Name() string
Init(*application.App) error
Shutdown()
CallableByJS() []string
InjectJS() string
}
```
`Name()`方法返回插件的名称。这用于记录目的。
`Init(*application.App) error`方法在加载插件时调用。`*application.App`参数是加载
插件的应用程序。任何错误都将阻止应用程序启动。
`Shutdown()`方法在应用程序关闭时调用。
`CallableByJS()`方法返回可以从前端调用的导出函数列表。这些方法名称必须与插件导出
的方法名称完全匹配。
`InjectJS()`方法返回应注入到创建的所有窗口中的JavaScript。这对于添加与插件补充的
自定义JavaScript函数很有用。
### 提示
#### 枚举
在Go中，枚举通常被定义为类型和一组常量。例如：
```go
type MyEnum int
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
由于Go和JavaScript之间的不兼容性，无法以这种方式使用自定义类型。最好的策略是为
float64使用类型别名：
```go
type MyEnum = float64
const (
MyEnumOne MyEnum = iota
MyEnumTwo
MyEnumThree
)
```
在Javascript中，您可以使用以下代码：
```js
const MyEnum = {
MyEnumOne: 0,
MyEnumTwo: 1,
MyEnumThree: 2,
};
```
- 为什么使用`float64`？不能使用`int`吗？
- 因为JavaScript没有“int”的概念。一切都是`number`，在Go中会转换为`float64`。Go
的反射包中还有类型转换的限制，这意味着使用`int`是行不通的。
### BackgroundColour
在v2中，这是指向`RGBA`结构的指针。在v3中，这是`RGBA`结构的值。
### WindowIsTranslucent
已删除此标志。现在有一个`BackgroundType`标志，可用于设置窗口应具有的背景类型。此
标志可以设置为以下任何值：
- `BackgroundTypeSolid` - 窗口将具有实心背景
- `BackgroundTypeTransparent` - 窗口将具有透明背景
- `BackgroundTypeTranslucent` - 窗口将具有半透明背景
在Windows上，如果`BackgroundType`设置为`BackgroundTypeTranslucent`，则可以使
用`WindowsWindow`选项中的`BackdropType`标志设置透明度的类型。这可以设置为以下任
何值：
- `Auto` - 窗口将使用系统确定的效果
- `None` - 窗口没有背景
- `Mica` - 窗口使用Mica效果
- `Acrylic` - 窗口使用丙烯酸效果
- `Tabbed` - 窗口使用选项卡效果
## Windows Application Options
### WndProcInterceptor
如果设置了此标志，将拦截WndProc并调用该函数。这允许您直接处理Windows消息。该函数
应具有以下签名：
```go
func(hwnd uintptr, msg uint32, wParam, lParam uintptr) (returnValue uintptr, shouldReturn)
```
如果`shouldReturn`值设置为`true`，则`returnValue`将由主wndProc方法返回。如果设置
为`false`，将忽略返回值，并且消息将继续由主wndProc方法处理。
## 在关闭时隐藏窗口+OnBeforeClose
在v2中，有一个`HideWindowOnClose`标志，用于在关闭窗口时隐藏窗
口。`HideWindowOnClose`标志与`OnBeforeClose`回调之间存在逻辑重叠。在v3中，已删
除`HideWindowOnClose`标志，并将`OnBeforeClose`回调重命名为`ShouldClose`。当用户
尝试关闭窗口时，将调用`ShouldClose`回调。如果回调返回`true`，窗口将关闭。如果返
回`false`，窗口将不会关闭。这可以用于隐藏窗口而不是关闭窗口。
## 窗口拖动
在v2中，使用`--wails-drag`属性来指示可以使用元素拖动窗口。在v3中，已将其替换
为`--webkit-app-region`，以更符合其他框架处理方式。`--webkit-app-region`属性可以
设置为以下任何值：
- `drag` - 可使用该元素拖动窗口
- `no-drag` - 该元素无法用于拖动窗口
我们本来希望使用`app-region`，但是在webkit在macOS上的`getComputedStyle`调用不支
持它。

185
mkdocs-website/docs/zh/development/introduction.md
View File

@ -1,185 +0,0 @@
# 介绍
!!! note 这个指南仍在制作中。
感谢您想要帮助开发Wails！本指南将帮助您入门。
## 入门指南
- Git 克隆此存储库。切换到 `v3-alpha` 分支。
- 安装 CLI：`cd v3/cmd/wails3 && go install`
- 可选：如果您想要使用构建系统构建前端代码，您需要安装
[npm](https://nodejs.org/en/download)。
## 构建
对于简单的程序，您可以使用标准的 `go build` 命令。也可以使用 `go run`。
Wails 还配备了一个构建系统，可用于构建更复杂的项目。它使用了强大的
[Task](https://taskfile.dev) 构建系统。要了解更多信息，请查看任务主页或运行
`wails task --help`。
## 项目结构
该项目具有以下结构：
```
v3
├── cmd/wails3 // CLI
├── examples // Wails 应用示例
├── internal // 内部包
| ├── runtime // Wails JS 运行时
| └── templates // 支持的项目模板
├── pkg
| ├── application // 核心 Wails 库
| └── events // 事件定义
| └── mac // 由插件使用的 macOS 特定代码
| └── w32 // Windows 特定代码
├── plugins // 支持的插件
├── tasks // 通用任务
└── Taskfile.yaml // 开发任务配置
```
## 开发
### 添加窗口功能
添加窗口功能的首选方法是在 `pkg/application/webview_window.go` 文件中添加一个新
函数。这应该实现所有平台所需的功能。任何特定于平台的代码都应通过
`webviewWindowImpl` 接口方法调用。该接口由每个目标平台实现，以提供平台特定的功
能。在某些情况下，这可能不执行任何操作。添加接口方法后，请确保每个平台都实现了
它。一个很好的例子是 `SetMinSize` 方法。
- Mac: `webview_window_darwin.go`
- Windows: `webview_window_windows.go`
- Linux: `webview_window_linux.go`
大多数，如果不是全部，特定于平台的代码应在主线程上运行。为了简化这一点，在
`application.go` 中定义了一些 `invokeSync` 方法。
### 更新运行时
运行时位于 `v3/internal/runtime`。更新运行时时，需要执行以下步骤：
```shell
wails3 task runtime:build
```
### 事件
事件定义在 `v3/pkg/events` 中。当添加新事件时，需要执行以下步骤：
- 将事件添加到 `events.txt` 文件中
- 运行 `wails3 task events:generate`
有几种类型的事件：特定于平台的应用程序和窗口事件 + 通用事件。通用事件对于跨平台
事件处理很有用，但您不必局限于“最低公共分母”。如果需要，可以使用特定于平台的事
件。
添加通用事件时，请确保映射了特定于平台的事件。一个示例是在
`window_webview_darwin.go` 中：
```go
// 将 ShouldClose 转化为通用的 WindowClosing 事件
w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
w.parent.emit(events.Common.WindowClosing)
})
```
注意：我们可能会尝试通过将映射添加到事件定义中来自动化此过程。
### 插件
插件是扩展 Wails 应用功能的一种方式。
#### 创建插件
插件是符合以下接口的标准 Go 结构：
```go
type Plugin interface {
Name() string
Init(*application.App) error
Shutdown()
CallableByJS() []string
InjectJS() string
}
```
`Name()` 方法返回插件的名称。这用于日志记录。
`Init(*application.App) error` 方法在加载插件时调用。`*application.App` 参数是加
载插件的应用程序。任何错误都将阻止应用程序启动。
`Shutdown()` 方法在应用程序关闭时调用。
`CallableByJS()` 方法返回可以从前端调用的导出函数列表。这些方法的名称必须与插件
导出的方法的名称完全匹配。
`InjectJS()` 方法返回应注入到所有窗口中的 JavaScript。这对于添加与插件相补充的自
定义 JavaScript 函数非常有用。
内置插件可以在 `v3/plugins` 目录中找到。参考它们以获得灵感。
## 任务
Wails CLI 使用 [Task](https://taskfile.dev) 构建系统。它作为库导入并用于运行
`Taskfile.yaml` 中定义的任务。与 Task 的主要交互发生在
`v3/internal/commands/task.go` 中。
### 升级 Taskfile
要检查是否有 Taskfile 的升级，请运行 `wails3 task -version` 并检查 Task 网站。
要升级使用的 Taskfile 版本，请运行：
```shell
wails3 task taskfile:upgrade
```
如果存在不兼容性，则应在 `v3/internal/commands/task.go` 文件中显示。
通常，修复不兼容性的最佳方法是克隆 `https://github.com/go-task/task` 上的任务存
储库，并查看 git 历史记录以确定发生了什么变化以及原因。
要检查所有更改是否正确工作，请重新安装 CLI 并再次检查版本：
```shell
wails3 task cli:install
wails3 task -version
```
## 打开 PR
确保所有 PR 都有与之关联的工单，以提供更改的上下文。如果没有工单，请先创建一个。
确保所有 PR 都已使用所做的更改更新了 CHANGELOG.md 文件。CHANGELOG.md 文件位于
`mkdocs-website/docs` 目录中。
## 其他任务
### 升级 Taskfile
Wails CLI 使用 [Task](https://taskfile.dev) 构建系统。它作为库导入并用于运行
`Taskfile.yaml` 中定义的任务。与 Task 的主要交互发生在
`v3/internal/commands/task.go` 中。
要检查是否有 Taskfile 的升级，请运行 `wails3 task -version` 并检查 Task 网站。
要升级使用的 Taskfile 版本，请运行：
```shell
wails3 task taskfile:upgrade
```
如果存在不兼容性，则应在 `v3/internal/commands/task.go` 文件中显示。
通常，修复不兼容性的最佳方法是克隆 `https://github.com/go-task/task` 上的任务存
储库，并查看 git 历史记录以确定发生了什么变化以及原因。
要检查所有更改是否正确工作，请重新安装 CLI 并再次检查版本：
```shell
wails3 task cli:install
wails3 task -version
```

382
mkdocs-website/docs/zh/development/status.md
View File

@ -1,382 +0,0 @@
将以下文本翻译为中文，并不要翻译 `!!! note` 或 `!!! tip` 或以此格式的字符串：
# 状态
v3版功能的状态。
!!! note
此列表包含公有和内部API支持的混合内容。<br/>
它不完整且可能不是最新的。
## 已知问题
- Linux尚未与Windows/Mac达到功能平衡
## 应用程序
应用程序接口方法
| 方法 | Windows | Linux | Mac | 备注 |
| ------------------------------------------------------------- | ------- | ----- | --- | ---- |
| run() error | Y | Y | Y | |
| destroy() | | Y | Y | |
| setApplicationMenu(menu \*Menu) | Y | Y | Y | |
| name() string | | Y | Y | |
| getCurrentWindowID() uint | Y | Y | Y | |
| showAboutDialog(name string, description string, icon []byte) | | Y | Y | |
| setIcon(icon []byte) | - | Y | Y | |
| on(id uint) | | | Y | |
| dispatchOnMainThread(fn func()) | Y | Y | Y | |
| hide() | Y | Y | Y | |
| show() | Y | Y | Y | |
| getPrimaryScreen() (\*Screen, error) | | Y | Y | |
| getScreens() ([]\*Screen, error) | | Y | Y | |
## Webview 窗口
Webview 窗口接口方法
| 方法 | Windows | Linux | Mac | 备注 |
| -------------------------------------------------- | ------- | ----- | --- | -------------------- |
| center() | Y | Y | Y | |
| close() | y | Y | Y | |
| destroy() | | Y | Y | |
| execJS(js string) | y | Y | Y | |
| focus() | Y | Y | | |
| forceReload() | | Y | Y | |
| fullscreen() | Y | Y | Y | |
| getScreen() (\*Screen, error) | y | Y | Y | |
| getZoom() float64 | | Y | Y | |
| height() int | Y | Y | Y | |
| hide() | Y | Y | Y | |
| isFullscreen() bool | Y | Y | Y | |
| isMaximised() bool | Y | Y | Y | |
| isMinimised() bool | Y | Y | Y | |
| maximise() | Y | Y | Y | |
| minimise() | Y | Y | Y | |
| nativeWindowHandle() (uintptr, error) | Y | Y | | |
| on(eventID uint) | y | | Y | |
| openContextMenu(menu *Menu, data *ContextMenuData) | y | | Y | |
| relativePosition() (int, int) | Y | Y | Y | |
| reload() | y | Y | Y | |
| run() | Y | Y | Y | |
| setAlwaysOnTop(alwaysOnTop bool) | Y | Y | Y | |
| setBackgroundColour(color RGBA) | Y | Y | Y | |
| setEnabled(bool) | | Y | Y | |
| setFrameless(bool) | | Y | Y | |
| setFullscreenButtonEnabled(enabled bool) | - | Y | Y | Windows 没有全屏按钮 |
| setHTML(html string) | Y | Y | Y | |
| setMaxSize(width, height int) | Y | Y | Y | |
| setMinSize(width, height int) | Y | Y | Y | |
| setRelativePosition(x int, y int) | Y | Y | Y | |
| setResizable(resizable bool) | Y | Y | Y | |
| setSize(width, height int) | Y | Y | Y | |
| setTitle(title string) | Y | Y | Y | |
| setURL(url string) | Y | Y | Y | |
| setZoom(zoom float64) | Y | Y | Y | |
| show() | Y | Y | Y | |
| size() (int, int) | Y | Y | Y | |
| toggleDevTools() | Y | Y | Y | |
| unfullscreen() | Y | Y | Y | |
| unmaximise() | Y | Y | Y | |
| unminimise() | Y | Y | Y | |
| width() int | Y | Y | Y | |
| zoom() | | Y | Y | |
| zoomIn() | Y | Y | Y | |
| zoomOut() | Y | Y | Y | |
| zoomReset() | Y | Y | Y | |
## 运行时
### 应用程序
| 功能 | Windows | Linux | Mac | 备注 |
| ---- | ------- | ----- | --- | ---- |
| 退出 | Y | Y | Y | |
| 隐藏 | Y | | Y | |
| 显示 | Y | | Y | |
### 对话框
| 功能 | Windows | Linux | Mac | 备注 |
| -------- | ------- | ----- | --- | ---- |
| 信息 | Y | Y | Y | |
| 警告 | Y | Y | Y | |
| 错误 | Y | Y | Y | |
| 问题 | Y | Y | Y | |
| 打开文件 | Y | | Y | |
| 保存文件 | Y | | Y | |
### 剪贴板
| 功能 | Windows | Linux | Mac | 备注 |
| -------- | ------- | ----- | --- | ---- |
| 设置文本 | Y | | Y | |
| 文本 | Y | | Y | |
### 上下文菜单
| 功能 | Windows | Linux | Mac | 备注 |
| -------------- | ------- | ----- | --- | ---- |
| 打开上下文菜单 | Y | | Y | |
| 默认开启 | | | | |
| 通过 HTML 控制 | Y | | | |
默认上下文菜单默认对所有`contentEditable: true`、`<input>`或`<textarea>`标签的元
素或具有`--default-contextmenu: true`样式的元素启
用。`--default-contextmenu: show`样式将始终显示上下文菜
单。`--default-contextmenu: hide`样式将始终隐藏上下文菜单。
嵌套在带有`--default-contextmenu: hide`样式的标签下的任何内容，除非使
用`--default-contextmenu: show`进行显式设置，否则不会显示上下文菜单。
### 屏幕
| 功能 | Windows | Linux | Mac | 备注 |
| ------------ | ------- | ----- | --- | ---- |
| 获取所有 | Y | Y | Y | |
| 获取主屏幕 | Y | Y | Y | |
| 获取当前屏幕 | Y | Y | Y | |
### 系统
| 功能 | Windows | Linux | Mac | 备注 |
| ------------ | ------- | ----- | --- | ---- |
| 是否为暗模式 | | | Y | |
### 窗口
Y = 支持 U = 未经测试
- = 不可用
| 功能 | Windows | Linux | Mac | 备注 |
| ------------------ | ------- | ----- | --- | ------------------------------------------------------------------------------------ |
| 居中 | Y | Y | Y | |
| 获得焦点 | Y | Y | | |
| 全屏 | Y | Y | Y | |
| 获得缩放比例 | Y | Y | Y | 获取当前视图比例 |
| 高度 | Y | Y | Y | |
| 隐藏 | Y | Y | Y | |
| 最大化 | Y | Y | Y | |
| 最小化 | Y | Y | Y | |
| 相对位置 | Y | Y | Y | |
| 屏幕 | Y | Y | Y | 获取窗口的屏幕 |
| 设置始终在顶部 | Y | Y | Y | |
| 设置背景颜色 | Y | Y | Y | https://github.com/MicrosoftEdge/WebView2Feedback/issues/1621#issuecomment-938234294 |
| 设置启用状态 | Y | U | - | 设置窗口是否可用 |
| 设置最大尺寸 | Y | Y | Y | |
| 设置最小尺寸 | Y | Y | Y | |
| 设置相对位置 | Y | Y | Y | |
| 设置是否可调整大小 | Y | Y | Y | |
| 设置大小 | Y | Y | Y | |
| 设置标题 | Y | Y | Y | |
| 设置缩放比例 | Y | Y | Y | 设置视图比例 |
| 显示 | Y | Y | Y | |
| 尺寸 | Y | Y | Y | |
| 取消全屏 | Y | Y | Y | |
| 取消最大化 | Y | Y | Y | |
| 取消最小化 | Y | Y | Y | |
| 宽度 | Y | Y | Y | |
| 缩放 | | Y | Y | |
| 放大 | Y | Y | Y | 增加视图比例 |
| 缩小 | Y | Y | Y | 减小视图比例 |
| 重置缩放 | Y | Y | Y | 重置视图比例 |
### 窗口选项
下表中的'Y'表示已经测试并且在窗口创建时应用了该选项。'X'表示该平台不支持该选项。
| 功能 | Windows | Linux | Mac | 备注 |
| ---------------- | ------- | ----- | --- | ------------------------------------ |
| 始终在顶部 | Y | | | |
| 背景颜色 | Y | Y | | |
| 背景类型 | | | | 默认情况下，亚克力效果有效，其他无效 |
| CSS | Y | Y | | |
| DevToolsEnabled | Y | Y | Y | |
| DisableResize | Y | Y | | |
| 启用拖放 | | Y | | |
| 启用欺诈网站警告 | | | | |
| 获得焦点 | Y | Y | | |
| 无边框 | Y | Y | | |
| 启用全屏按钮 | Y | | | Windows上没有全屏按钮 |
| HTML | Y | Y | | |
| JS | Y | Y | | |
| Mac | - | - | | |
| 最大高度 | Y | Y | | |
| 最大宽度 | Y | Y | | |
| 最小高度 | Y | Y | | |
| 最小宽度 | Y | Y | | |
| 名称 | Y | Y | | |
| 启动时打开检查器 | | | | |
| 启动状态 | Y | | | |
| 标题 | Y | Y | | |
| URL | Y | Y | | |
| 宽度 | Y | Y | | |
| Windows | Y | - | - | |
| X | Y | Y | | |
| Y | Y | Y | | |
| 缩放 | | | | |
| 启用缩放控件 | | | | |
### 日志
要记录还是不要记录？系统日志器与自定义日志器。
## 菜单
| 事件 | Windows | Linux | Mac | 备注 |
| ---------------- | ------- | ----- | --- | ---- |
| 默认应用程序菜单 | Y | Y | Y | |
## 托盘菜单
| 功能 | Windows | Linux | Mac | 备注 |
| -------------- | ------- | ----- | --- | -------------------------------------------------- |
| 图标 | Y | | Y | Windows具有默认的浅色/深色模式图标并支持PNG或ICO。 |
| 标签 | - | | Y | |
| 标签（ANSI码） | - | | | |
| 菜单 | Y | | Y | |
### 方法
| 方法 | Windows | Linux | Mac | 备注 |
| ----------------------------- | ------- | ----- | --- | ---- |
| setLabel(label string) | - | | Y | |
| run() | Y | | Y | |
| setIcon(icon []byte) | Y | | Y | |
| setMenu(menu \*Menu) | Y | | Y | |
| setIconPosition(position int) | - | | Y | |
| setTemplateIcon(icon []byte) | - | | Y | |
| destroy() | Y | | Y | |
| setDarkModeIcon(icon []byte) | Y | | Y | |
## 跨平台事件
将本机事件映射到跨平台事件。
| 事件 | Windows | Linux | Mac | 备注 |
| ------------------------ | ------- | ----- | --------------- | ---- |
| WindowWillClose | | | WindowWillClose | |
| WindowDidClose | | | | |
| WindowDidResize | | | | |
| WindowDidHide | | | | |
| ApplicationWillTerminate | | | | |
... 添加更多
## 绑定生成
工作正常。
## 模型生成
工作正常。
## 任务文件
包含很多开发所需的内容。
## 主题
| 模式 | Windows | Linux | Mac | 备注 |
| ---- | ------- | ----- | --- | ---- |
| 暗 | Y | | | |
| 亮 | Y | | | |
| 系统 | Y | | | |
## NSIS安装程序
待定
## 模板
所有模板都可用。
## 插件
内置插件支持：
| 插件 | Windows | Linux | Mac | 备注 |
| ---------- | ------- | ----- | --- | ---- |
| 浏览器 | Y | | Y | |
| KV 存储 | Y | Y | Y | |
| 日志 | Y | Y | Y | |
| 单实例 | Y | | Y | |
| SQLite | Y | Y | Y | |
| 开机自启动 | Y | | Y | |
| 服务器 | | | | |
待办事项：
- 确保每个插件都有一个可以注入到窗口中的JS包装器。
## 打包
| | Windows | Linux | Mac | 备注 |
| ------------------ | ------- | ----- | --- | ---- |
| 图标生成 | Y | | Y | |
| 图标嵌入 | Y | | Y | |
| Info.plist | - | | Y | |
| NSIS 安装程序 | | | - | |
| Mac 包 | - | | Y | |
| Windows 可执行文件 | Y | | - | |
## 无边框窗口
| 功能 | Windows | Linux | Mac | 备注 |
| -------- | ------- | ----- | --- | ---------------------------------- |
| 调整大小 | Y | | Y | |
| 拖拽 | Y | Y | Y | Linux-始终可以使用 `Meta`+左键拖拽 |
## Mac 特定
- [x] 半透明
### Mac 选项
| 功能 | 默认值 | 备注 |
| -------------- | ----------------- | ---------------------------------- |
| 背景 | MacBackdropNormal | 标准的实心窗口 |
| 禁用阴影 | false | |
| 标题栏 | | 默认情况下使用标准的窗口装饰 |
| 外观 | DefaultAppearance | |
| 隐藏标题栏高度 | 0 | 为无边框窗口创建一个不可见的标题栏 |
| 禁用阴影 | false | 禁用窗口投影阴影 |
## Windows 特定
- [x] 半透明
- [x] 自定义主题
### Windows 选项
| 功能 | 默认值 | 备注 |
| ------------------ | ------------- | -------------------- |
| 背景类型 | Solid | |
| 禁用图标 | false | |
| 主题 | SystemDefault | |
| 自定义主题 | nil | |
| 禁用无边框窗口装饰 | false | |
| 窗口遮罩 | nil | 使窗口成为位图的内容 |
## Linux 特定
由`*_linux.go`文件使用的函数的实现详细信息位于以下文件中：
- linux_cgo.go：CGo 实现
- linux_purego.go：PureGo 实现
### CGO
默认情况下，使用 CGO 编译 Linux 端口。这会阻止轻松的交叉编译，因此同时也正在同时
开发 PureGo 实现。
### Purego
可以使用以下命令编译示例：
CGO_ENABLED=0 go build -tags purego
注意：重构之后的功能目前无法正常工作。

66
mkdocs-website/docs/zh/getting-started/feedback.md
View File

@ -1,66 +0,0 @@
# 反馈
我们欢迎（并鼓励）您的反馈！在创建新的反馈之前，请先搜索现有的票据或帖子。以下是
提供反馈的不同方式：
=== "错误"
如果您发现了一个错误，请通过在Discord上发布到[v3 Alpha 反馈](https://discord.gg/3mgVyGua)频道来告知我们。
- 帖子应清楚地说明是什么错误，并提供一个简单的可复现示例。如果文档对于*应该*发生什么不清楚，请在帖子中包括这一点。
- 帖子应该被标记为`Bug`标签。
- 请在您的帖子中包括`wails doctor`的输出结果。
- 如果错误是与当前文档不一致的行为，例如窗口无法正确调整大小，请执行以下操作：
- 在`v3/example`目录中更新一个现有示例或在`v3/examples`文件夹中创建一个清楚显示问题的新示例。
- 使用标题为“[v3 alpha test] <错误描述>”的[PR](https://github.com/wailsapp/wails/pulls)打开一个请求。
- 请在您的帖子中包括指向PR的链接。
!!! warning
*记住*，异常行为不一定是错误 - 它可能只是不按照您预期的方式工作。请使用[建议](#suggestions)来反馈这类情况。
=== "修复"
如果您有一个错误的修复或文档的更新，请执行以下操作：
- 在[Wails存储库](https://github.com/wailsapp/wails)上创建一个拉取请求。PR的标题应以`[v3 alpha]`开头。
- 在[v3 Alpha Feedback](https://discord.gg/3mgVyGua)频道中发布帖子。
- 帖子应标记为`PR`。
- 请在帖子中包含PR的链接。
=== "建议"
如果您有建议，请在Discord的[v3 Alpha Feedback](https://discord.gg/3mgVyGua)频道中发布信息：
- 帖子应标记为`Suggestion`。
如果您有任何问题，请随时在[Discord](https://discord.gg/3mgVyGua)上联系我们。
=== "投票"
- 可以使用:thumbsup:表情符号给帖子投票。请对您认为优先级较高的帖子进行投票。
- 请*不要*只添加"+1"或"me too"等评论。
- 如果帖子还有更多内容可补充，请随时发表评论，例如"此错误也影响ARM构建"或"另一种选项是......"
已知问题和正在进行的工作列表可以
在[此处](https://github.com/orgs/wailsapp/projects/6)找到。
## 我们寻求反馈的内容
- API
- 使用起来方便吗？
- 它是否按照您的期望工作？
- 有什么遗漏的功能吗？
- 应该删除什么？
- Go和JS之间是否一致？
- 构建系统
- 使用起来方便吗？
- 我们能改进吗？
- 示例
- 是否清晰？
- 是否涵盖了基础知识？
- 功能
- 哪些功能缺失？
- 哪些功能是不需要的？
- 文档
- 有什么可以更清晰的地方？

77
mkdocs-website/docs/zh/getting-started/installation.md
View File

@ -1,77 +0,0 @@
# 安装
要安装Wails CLI，请确保已经安装[Go 1.21+](https://go.dev/dl/)并运行以下命令：
```shell
git clone https://github.com/wailsapp/wails.git
cd wails
git checkout v3-alpha
cd v3/cmd/wails3
go install
```
## 支持的平台
- Windows 10/11 AMD64/ARM64
- MacOS 10.13+ AMD64
- MacOS 11.0+ ARM64
- Ubuntu 22.04 AMD64/ARM64（其他Linux可能也可以工作！）
## 依赖项
在安装之前，Wails有一些常见的依赖项需要安装：
=== "Go 1.21+"
从[Go下载页面](https://go.dev/dl/)下载Go。
确保按照官方的[Go安装指南](https://go.dev/doc/install)进行操作。您还需要确保您的`PATH`环境变量中包含`~/go/bin`目录的路径。重新启动终端并进行以下检查：
- 检查Go是否已正确安装：`go version`
- 检查`~/go/bin`是否在您的PATH变量中：`echo $PATH | grep go/bin`
=== "npm（可选）"
虽然Wails不需要安装npm，但如果您想使用捆绑的模板，则需要安装npm。
从[Node下载页面](https://nodejs.org/en/download/)下载最新的node安装程序。最好使用最新的版本，因为这是我们通常进行测试的版本。
运行`npm --version`进行验证。
=== "Task（可选）"
Wails CLI嵌入了一个名为[Task](https://taskfile.dev/#/installation)的任务运行器。这是可选的，但建议安装。如果您不想安装Task，可以使用`wails3 task`命令代替`task`。
安装Task将给您最大的灵活性。
## 平台特定的依赖项
您还需要安装特定于平台的依赖项：
=== "Mac"
Wails要求安装xcode命令行工具。可以通过运行以下命令来完成：
```
xcode-select --install
```
=== "Windows"
Wails要求安装[WebView2 Runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/)。一些Windows安装可能已经安装了此软件。您可以使用`wails doctor`命令检查。
=== "Linux"
Linux需要标准的`gcc`构建工具以及`libgtk3`和`libwebkit`。而不是列出不同发行版的大量命令，Wails可以尝试确定您特定发行版的安装命令。安装后运行<code>wails doctor</code>，将显示如何安装依赖项。如果您的发行版/软件包管理器不受支持，请在discord上告诉我们。
## 系统检查
运行`wails3 doctor`将检查您是否安装了正确的依赖项。如果没有安装，它将提供缺失的
内容，并帮助您解决任何问题。
## 看起来缺少`wails3`命令？
如果系统报告缺少`wails3`命令，请检查以下内容：
- 确保您已正确按照Go安装指南进行操作。
- 检查`go/bin`目录是否在`PATH`环境变量中。
- 关闭/重新打开当前终端以使用新的`PATH`变量。

34
mkdocs-website/docs/zh/getting-started/next-steps.md
View File

@ -1,34 +0,0 @@
# 下一步
现在您已经安装了Wails，可以开始探索alpha版本。
最好的起点是Wails存储库中的`examples`目录。其中包含了一些可以运行和玩耍的示例。
## 运行示例
要运行示例，您可以简单地使用：
```shell
go run .
```
在示例目录中。
示例的状态在[路线图](../roadmap.md)中说明。
## 创建新项目
要创建新项目，可以使用`wails3 init`命令。这将在当前目录中创建一个新项目。
Wails3默认使用[Task](https://taskfile.dev)作为其构建系统，尽管您可以使用自己的构
建系统，或直接使用`go build`。Wails内置了任务构建系统，可以使用`wails3 task`运
行。
如果查看`Taskfile.yaml`文件，您会看到有一些任务被定义。最重要的任务是`build`任
务。这是在使用`wails3 build`时运行的任务。
任务文件可能不完整，并且可能会随时间变化而改变。
## 构建项目
要构建项目，可以使用`wails3 build`命令。这是`wails3 task build`的快捷方式。

5
mkdocs-website/docs/zh/index.md
View File

@ -1,5 +0,0 @@
---
template: home.zh.html
---
欢迎来到 Wails 项目

41
mkdocs-website/docs/zh/roadmap.md
View File

@ -1,41 +0,0 @@
# 路线图
路线图是一个活动文档，可能会有所变动。如果您有任何建议，请提出一个问题。每个里程
碑都会有一系列我们力争实现的目标。这些目标可能会有所变动。
## Alpha 里程碑
### Alpha 2
#### 目标
阿尔法 2 的目标是引入 [Taskfile](https://taskfile.dev) 支持。这将
使我们能够拥有一个单一的、可扩展的构建系统，适用于所有平台。
我们还希望让所有示例在 Linux 上都能运行。
#### 状态
- [ ] 所有示例在 Linux 上运行
- [ ] 初始化、构建、开发和打包命令
- :material-check-bold: - 工作正常
- :material-minus: - 部分工作
- :material-close: - 无法工作
{{ read_csv("alpha2.csv") }}
### Alpha 1
#### 目标
Alpha 1 是最初的发布版本。旨在收集关于新 API 的反馈，并让人们进行实验。主要目标
是使大多数示例在所有平台上都能正常工作。
#### 状态
- :material-check-bold: - 工作正常
- :material-minus: - 部分工作
- :material-close: - 无法工作
{{ read_csv("alpha1.csv") }}

323
mkdocs-website/docs/zh/whats-new.md
View File

@ -1,323 +0,0 @@
# v3有哪些新功能？
!!! note v3版本中将包含的功能可能会有所更改。
## 多窗口
现在可以创建多个窗口，并对每个窗口进行独立配置。
```go
package main
import (
_ "embed"
"log"
"github.com/wailsapp/wails/v3/pkg/application"
)
//go:embed assets/*
var assets embed.FS
func main() {
app := application.New(application.Options{
Name: "多窗口演示",
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
})
window1 := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
Title: "窗口1",
})
window2 := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
Title: "窗口2",
})
// 从embed.FS加载嵌入的html
window1.SetURL("/")
window1.Center()
// 加载外部URL
window2.SetURL("https://wails.app")
err := app.Run()
if err != nil {
log.Fatal(err.Error())
}
}
```
## 系统托盘
系统托盘允许您在桌面的系统托盘区域添加一个图标，并具有以下功能：
- 附加窗口（窗口将居中于系统托盘图标）
- 完整的菜单支持
- 亮/暗模式图标
```go
package main
import (
_ "embed"
"log"
"runtime"
"github.com/wailsapp/wails/v3/pkg/application"
"github.com/wailsapp/wails/v3/pkg/icons"
)
func main() {
app := application.New(application.Options{
Name: "系统托盘演示",
Mac: application.MacOptions{
ActivationPolicy: application.ActivationPolicyAccessory,
},
})
window := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
Width: 500,
Height: 800,
Frameless: true,
AlwaysOnTop: true,
Hidden: true,
Windows: application.WindowsWindow{
HiddenOnTaskbar: true,
},
})
systemTray := app.NewSystemTray()
// macOS上的模板图标支持
if runtime.GOOS == "darwin" {
systemTray.SetTemplateIcon(icons.SystrayMacTemplate)
} else {
// 亮/暗模式图标支持
systemTray.SetDarkModeIcon(icons.SystrayDark)
systemTray.SetIcon(icons.SystrayLight)
}
// 菜单支持
myMenu := app.NewMenu()
myMenu.Add("Hello World!").OnClick(func(_ *application.Context) {
println("Hello World!")
})
systemTray.SetMenu(myMenu)
// 这将使窗口居中于系统托盘图标，偏移量为5px
// 单击系统托盘图标时，它将自动显示
// 当窗口失去焦点时隐藏
systemTray.AttachWindow(window).WindowOffset(5)
err := app.Run()
if err != nil {
log.Fatal(err)
}
}
```
## 插件
插件允许您扩展Wails系统的功能。不仅可以在Go中使用插件方法，还可以从Javascript中
调用插件方法。包含的插件有：
- kvstore - 键/值存储
- browser - 在浏览器中打开链接
- log - 自定义日志记录器
- oauth - 处理OAuth身份验证并支持60个提供商
- single_instance - 仅允许运行一个应用程序副本
- sqlite - 向应用程序添加SQLite数据库。使用现代纯Go库
- start_at_login - 注册/注销应用程序以在登录时启动
## 改进的绑定生成
v3使用新的静态分析器生成绑定。这使得生成绑定非常快速，并保留了绑定中的注释和参数
名称。默认情况下，绑定使用ID而不是字符串进行调用。这提供了性能提升，并允许使用混
淆工具，如[garble](https://github.com/burrowers/garble)。
通过在项目目录中运行 `wails3 generate bindings` 来生成绑定。
```js
// @ts-check
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
import { main } from "./models";
window.go = window.go || {};
window.go.main = {
GreetService: {
/**
* GreetService.Greet
* Greet greets a person
* @param name {string}
* @returns {Promise<string>}
**/
Greet: function (name) {
wails.CallByID(1411160069, ...Array.prototype.slice.call(arguments, 0));
},
/**
* GreetService.GreetPerson
* GreetPerson greets a person
* @param person {main.Person}
* @returns {Promise<string>}
**/
GreetPerson: function (person) {
wails.CallByID(4021313248, ...Array.prototype.slice.call(arguments, 0));
},
},
};
```
## 改进的构建系统
在v2中，构建系统完全不透明且难以自定义。在v3中，可以使用标准的Go工具构建所有内
容。
v2构建系统完成的所有繁重工作，例如图标生成，已作为CLI中的工具命令添加。我们
将[Taskfile](https://taskfile.dev)整合到CLI中，以协调这些调用，以带来与v2相同的
开发人员体验。然而，这种方法在灵活性和易用性之间达到了最佳平衡，因为现在您可以根
据需要自定义构建过程。
您甚至可以使用make，如果那是您的菜！
```yaml title="来自Taskfile.yml的片段"
build:darwin:
summary: 构建应用程序
platforms:
- darwin
cmds:
- task: pre-build
- task: build-frontend
- go build -gcflags=all="-N -l" -o bin/{{.APP_NAME}}
- task: post-build
env:
CGO_CFLAGS: "-mmacosx-version-min=10.13"
CGO_LDFLAGS: "-mmacosx-version-min=10.13"
MACOSX_DEPLOYMENT_TARGET: "10.13"
```
## 改进的事件
现在为许多运行时操作发出事件，允许您挂钩应用程序/系统事件。在存在常见平台事件的
地方，还发出了跨平台（通用）事件，允许您在跨平台上编写相同的事件处理方法。
还可以注册事件钩子。这些钩子类似于`On`方法，但是是同步的，并允许您取消事件。例
如，在关闭窗口之前显示确认对话框的示例。
```go
package main
import (
_ "embed"
"log"
"time"
"github.com/wailsapp/wails/v3/pkg/application"
"github.com/wailsapp/wails/v3/pkg/events"
)
//go:embed assets
var assets embed.FS
func main() {
app := application.New(application.Options{
Name: "Events Demo",
Description: "Events API演示",
Assets: application.AssetOptions{
Handler: application.AssetFileServerFS(assets),
},
Mac: application.MacOptions{
ApplicationShouldTerminateAfterLastWindowClosed: true,
},
})
// 自定义事件处理
app.Events.On("myevent", func(e *application.WailsEvent) {
log.Printf("[Go] 收到WailsEvent事件: %+v\n", e)
})
// 特定于操作系统的应用程序事件
app.On(events.Mac.ApplicationDidFinishLaunching, func(event *application.Event) {
println("events.Mac.ApplicationDidFinishLaunching触发！")
})
// 平台无关事件
app.On(events.Common.ApplicationStarted, func(event *application.Event) {
println("events.Common.ApplicationStarted触发！")
})
win1 := app.NewWebviewWindowWithOptions(application.WebviewWindowOptions{
Title: "关闭我需要3次确认！",
})
var countdown = 3
// 注册钩子以取消窗口关闭
win1.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
countdown--
if countdown == 0 {
println("关闭！")
return
}
println("不行！不关闭！")
e.Cancel()
})
win1.On(events.Common.WindowFocus, func(e *application.WindowEvent) {
println("[事件] 窗口焦点！")
})
err := app.Run()
if err != nil {
log.Fatal(err.Error())
}
}
```
## Wails标记语言（wml）
一种实验性的功能，使用纯HTML调用运行时方法，类似于[htmx](https://htmx.org)。
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Wails ML演示</title>
</head>
<body style="margin-top:50px; color: white; background-color: #191919">
<h2>Wails ML演示</h2>
<p>此应用程序不包含任何Javascript！</p>
<button wml-event="button-pressed">按我！</button>
<button wml-event="delete-things" wml-confirm="确定吗？">
删除所有内容！
</button>
<button wml-window="Close" wml-confirm="确定吗？">关闭窗口？</button>
<button wml-window="Center">居中</button>
<button wml-window="Minimise">最小化</button>
<button wml-window="Maximise">最大化</button>
<button wml-window="UnMaximise">取消最大化</button>
<button wml-window="Fullscreen">全屏</button>
<button wml-window="UnFullscreen">取消全屏</button>
<button wml-window="Restore">还原</button>
<div
style="width: 200px; height: 200px; border: 2px solid white;"
wml-event="hover"
wml-trigger="mouseover"
>
悬停在我上面
</div>
</body>
</html>
```

43
mkdocs-website/mkdocs.yml
View File

@ -48,6 +48,27 @@ theme:
toggle:
icon: material/toggle-switch
name: Switch to light mode
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.inlinehilite
- pymdownx.snippets:
restrict_base_path: false
- pymdownx.details
- pymdownx.superfences
- pymdownx.mark
- attr_list
- admonition
- footnotes
- toc:
permalink: '#'
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
plugins:
- table-reader:
@ -170,28 +191,6 @@ nav:
- Change Log: changelog.md
- Sponsor❤️: https://github.com/sponsors/leaanthony
markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.inlinehilite
- pymdownx.snippets:
restrict_base_path: false
- pymdownx.details
- pymdownx.superfences
- pymdownx.mark
- attr_list
- admonition
- footnotes
- toc:
permalink: '#'
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
watch:
- overrides
- shared

BIN
mkdocs-website/requirements.txt
View File

Binary file not shown.