Wails v3 的新功能

Wails v3 相較於 v2 有重大變革。它以更靈活的程序式方法取代了單一視窗的宣告式 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 目錄中還有更多範例，快去看看吧！

無障礙功能

編輯此文件