Wails v3 的新增功能

与v2相比，Wails v3引入了重大变更。它以更灵活的过程式方法取代了单窗口声明式 API。这种新的 API 设计提高了代码可读性并简化了开发，尤其适合复杂的多窗口应用程序。

Wails v3标志着使用 Go 和 Web 技术构建桌面应用程序的方式实现了重大演进。

多窗口

Wails v3引入了在单个应用程序中创建和管理多个窗口的能力。借助此功能，开发者可以突破单窗口应用程序的限制，设计更复杂、更灵活的用户界面。

每个窗口都可以独立配置，从而灵活控制其大小、位置、内容和行为。这样便可创建针对不同功能使用独立窗口的应用程序，例如主界面、设置面板或辅助视图。

开发者可以通过编程方式创建、操作和管理这些窗口，从而构建可适应用户需求和应用程序状态的动态用户界面。

示例

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:   "Multi Window Demo",
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assets),
        },
   })
   
   window1 := app.Window.NewWithOptions(application.WebviewWindowOptions{
       Title:  "Window 1",
   })
   
   window2 := app.Window.NewWithOptions(application.WebviewWindowOptions{
       Title:  "Window 2",
   })
   
   // load the embedded html from the embed.FS
   window1.SetURL("/")
   window1.Center()
   
   // Load an external URL
   window2.SetURL("https://wails.io")
   
   err := app.Run()

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

系统托盘集成

Wails v3为系统托盘功能提供了强大支持，使应用程序能够持续驻留在用户桌面上。此功能尤其适用于需要在后台运行或让用户快速访问关键功能的应用程序。

Wails v3系统托盘集成的主要功能包括：

窗口附加：可以将窗口与系统托盘图标关联。激活时，该窗口会相对于图标位置居中显示，为用户快速访问应用程序提供了极为便捷的方式。
全面的菜单支持：创建内容丰富的交互式菜单，让用户可直接通过系统托盘图标访问。这样无需打开完整的应用程序窗口即可快速执行操作。
自适应图标显示：同时支持浅色和深色模式图标，确保应用程序的系统托盘图标在不同系统主题下始终清晰可见且美观。macOS 还支持模板图标。

示例

package main

import (
    "log"
    "runtime"

    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/icons"
)

func main() {
    app := application.New(application.Options{
        Name:        "Systray Demo",
        Mac: application.MacOptions{
            ActivationPolicy: application.ActivationPolicyAccessory,
        },
    })

    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Width:       500,
        Height:      800,
        Frameless:   true,
        AlwaysOnTop: true,
        Hidden:      true,
        Windows: application.WindowsWindow{
            HiddenOnTaskbar: true,
        },
    })

    systemTray := app.SystemTray.New()

    // Support for template icons on macOS
    if runtime.GOOS == "darwin" {
        systemTray.SetTemplateIcon(icons.SystrayMacTemplate)
    } else {
        // Support for light/dark mode icons
        systemTray.SetDarkModeIcon(icons.SystrayDark)
        systemTray.SetIcon(icons.SystrayLight)
    }

    // Support for menu
    myMenu := app.Menu.New()
    myMenu.Add("Hello World!").OnClick(func(_ *application.Context) {
        println("Hello World!")
    })
    systemTray.SetMenu(myMenu)

    // This will center the window to the systray icon with a 5px offset
    // It will automatically be shown when the systray icon is clicked
    // and hidden when the window loses focus
    systemTray.AttachWindow(window).WindowOffset(5)

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

改进的绑定生成

Wails v3显著改进了项目的绑定生成方式。绑定是连接 Go 后端与前端的纽带，让两者能够无缝通信。

现在使用功能强大的静态分析器生成绑定，从根本上改进了绑定生成流程。它不仅提升了速度，还会保留注释和参数名称，从而维持代码质量。

绑定生成流程现已简化，只需执行一条命令：wails3 generate bindings。

示例

// @ts-check
// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT

// Generated layout (excerpt): frontend/bindings/<full-go-import-path>/greetservice.js
import { Call as $Call, Create as $Create } from "/wails/runtime.js";

/**
 * Greet greets a person
 * @param {string} $0
 * @returns {Promise<string>}
 */
export function Greet($0) {
    return $Call.ByID(1411160069, $0);
}

/**
 * GreetPerson greets a person
 * @param {main.Person} $0
 * @returns {Promise<string>}
 */
export function GreetPerson($0) {
    return $Call.ByID(4021313248, $0);
}

改进的构建系统

Wails v3引入了更灵活、更透明的构建系统，解决了上一版本的局限。在v2中，构建过程大多不透明且难以自定义，这可能会让希望更好地掌控项目构建过程的开发者感到困扰。

v2构建系统曾经承担的所有繁重工作（例如生成图标和创建清单）都已作为工具命令添加到 CLI 中。我们将Taskfile集成到 CLI 中，用它编排这些调用，从而提供与v2相同的开发体验。同时，这种方式在灵活性与易用性之间实现了最佳平衡，因为现在可以根据需要自定义构建过程。

如果你偏爱 make，甚至也可以使用它！

示例

build/Taskfile.darwin.yml

yaml

darwin:build:
  summary: Builds the application for macOS
  platforms:
    - darwin
  cmds:
    - task: common:go:mod:tidy
    - task: common:build:frontend
    - task: common:generate:icons
    - task: darwin:build:app
  env:
    CGO_CFLAGS: "-mmacosx-version-min=10.15"
    CGO_LDFLAGS: "-mmacosx-version-min=10.15"
    MACOSX_DEPLOYMENT_TARGET: "10.15"

改进的事件

Wails 现在会针对各种运行时操作和系统活动发出事件。这使你的应用程序能够实时响应这些事件。此外，还提供了跨平台（通用）事件，让你能够编写可在不同操作系统上一致工作的事件处理方法。

可以注册事件钩子来同步处理特定事件。与 On方法不同，这些钩子允许你在需要时取消事件。一个常见用例是在关闭窗口前显示确认对话框。这样，你就能更好地控制事件流程和用户体验。

示例

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: "A demo of the Events API",
        Assets: application.AssetOptions{
            Handler: application.AssetFileServerFS(assets),
        },
        Mac: application.MacOptions{
            ApplicationShouldTerminateAfterLastWindowClosed: true,
        },
    })

    // Custom event handling — App.Event.On(name, func(e *CustomEvent))
    app.Event.On("myevent", func(e *application.CustomEvent) {
        log.Printf("[Go] CustomEvent received: %+v\n", e)
    })

    // OS-specific application events — App.Event.OnApplicationEvent(eventType, func(e *ApplicationEvent))
    app.Event.OnApplicationEvent(events.Mac.ApplicationDidFinishLaunching, func(event *application.ApplicationEvent) {
        println("events.Mac.ApplicationDidFinishLaunching fired!")
    })

    // Platform-agnostic events
    app.Event.OnApplicationEvent(events.Common.ApplicationStarted, func(event *application.ApplicationEvent) {
        println("events.Common.ApplicationStarted fired!")
    })

    win1 := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title: "Takes 3 attempts to close me!",
    })

    var countdown = 3

    // Register a hook to cancel the window closing
    win1.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        countdown--
        if countdown == 0 {
            println("Closing!")
            return
        }
        println("Nope! Not closing!")
        e.Cancel()
    })

    win1.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        println("[Event] Window focus!")
    })

    err := app.Run()

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

Wails 标记语言（wml）

这是一项实验性功能，可使用纯 HTML 调用运行时方法，类似于 htmx。

示例

html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Wails ML Demo</title>
  </head>
  <body style="margin-top:50px; color: white; background-color: #191919">
    <h2>Wails ML Demo</h2>
    <p>This application contains no Javascript!</p>
    <button wml-event="button-pressed">Press me!</button>
    <button wml-event="delete-things" wml-confirm="Are you sure?">
      Delete all the things!
    </button>
    <button wml-window="Close" wml-confirm="Are you sure?">
      Close the Window?
    </button>
    <button wml-window="Center">Center</button>
    <button wml-window="Minimise">Minimise</button>
    <button wml-window="Maximise">Maximise</button>
    <button wml-window="UnMaximise">UnMaximise</button>
    <button wml-window="Fullscreen">Fullscreen</button>
    <button wml-window="UnFullscreen">UnFullscreen</button>
    <button wml-window="Restore">Restore</button>
    <div
      style="width: 200px; height: 200px; border: 2px solid white;"
      wml-event="hover"
      wml-trigger="mouseover"
    >
      Hover over me
    </div>
  </body>
</html>

示例

examples 目录中还提供了更多示例。快去看看吧！

无障碍

编辑此文档