API приложения

Обзор

Application — это ядро вашего приложения Wails. Оно управляет окнами, службами и событиями, а также предоставляет доступ ко всем возможностям платформы.

Создание приложения

import "github.com/wailsapp/wails/v3/pkg/application"

app := application.New(application.Options{
    Name:        "My App",
    Description: "My awesome application",
    Services: []application.Service{
        application.NewService(&MyService{}),
    },
})

Основные методы

Run()

Запускает цикл обработки событий приложения.

func (a *App) Run() error

Пример:

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

Возвращаемое значение: ошибка, если запуск завершился неудачей

Quit()

Корректно завершает работу приложения.

func (a *App) Quit()

Пример:

// In a menu handler
menu.Add("Quit").OnClick(func(ctx *application.Context) {
    app.Quit()
})

Config()

Возвращает конфигурацию приложения.

func (a *App) Config() Options

Пример:

config := app.Config()
fmt.Println("App name:", config.Name)

Управление окнами

app.Window.New()

Создаёт новое окно webview с параметрами по умолчанию.

func (wm *WindowManager) New() *WebviewWindow

Пример:

window := app.Window.New()
window.Show()

app.Window.NewWithOptions()

Создаёт новое окно webview с пользовательскими параметрами.

func (wm *WindowManager) NewWithOptions(options WebviewWindowOptions) *WebviewWindow

Пример:

window := app.Window.NewWithOptions(application.WebviewWindowOptions{
    Title:  "My Window",
    Width:  800,
    Height: 600,
    BackgroundColour: application.NewRGB(255, 255, 255),
})

app.Window.GetByName()

Получает окно по его имени. Возвращает окно и признак того, было ли оно найдено.

func (wm *WindowManager) GetByName(name string) (Window, bool)

Пример:

if window, ok := app.Window.GetByName("main"); ok {
    window.Show()
}

app.Window.GetAll()

Возвращает все окна приложения.

func (wm *WindowManager) GetAll() []Window

Пример:

windows := app.Window.GetAll()
for _, window := range windows {
    fmt.Println("Window:", window.Name())
}

Менеджеры

Application предоставляет через свойства доступ к различным менеджерам:

app.Window       // Window management
app.Menu         // Menu management
app.Dialog       // Dialog management
app.Event        // Event management
app.Clipboard    // Clipboard operations
app.Screen       // Screen information
app.SystemTray   // System tray
app.Browser      // Browser operations
app.Env          // Environment variables
app.ContextMenu  // Context-menu management
app.KeyBinding   // Global keyboard shortcuts
app.Logger       // *slog.Logger

Пример использования

// Create window
window := app.Window.New()

// Show dialog
app.Dialog.Info().SetMessage("Hello!").Show()

// Copy to clipboard
app.Clipboard.SetText("Copied text")

// Get screens
screens := app.Screen.GetAll()

Управление службами

RegisterService()

Регистрирует службу в приложении.

func (a *App) RegisterService(service Service)

RegisterService ничего не возвращает; ошибки инициализации службы проявляются как сбои ServiceStartup во время app.Run().

Пример:

type MyService struct {
    app *application.App
}

func NewMyService(app *application.App) *MyService {
    return &MyService{app: app}
}

// Register after app creation
app.RegisterService(application.NewService(NewMyService(app)))

Управление событиями

app.Event.Emit()

Генерирует пользовательское событие. Возвращает true, если перехватчик отменил генерацию события.

func (em *EventManager) Emit(name string, data ...any) bool

Пример:

// Emit event with data
app.Event.Emit("user-logged-in", map[string]interface{}{
    "username": "john",
    "timestamp": time.Now(),
})

app.Event.On()

Отслеживает пользовательские события. Возвращает func() для отмены подписки.

func (em *EventManager) On(name string, callback func(*CustomEvent)) func()

Пример:

app.Event.On("user-logged-in", func(e *application.CustomEvent) {
    data := e.Data.(map[string]interface{})
    username := data["username"].(string)
    fmt.Println("User logged in:", username)
})

app.Event.OnApplicationEvent()

Отслеживает события жизненного цикла приложения. Параметр eventType имеет тип events.ApplicationEventType (из пакета events).

func (em *EventManager) OnApplicationEvent(
    eventType events.ApplicationEventType,
    callback func(*ApplicationEvent),
) func()

Пример:

import "github.com/wailsapp/wails/v3/pkg/events"

// Listen for app-started
app.Event.OnApplicationEvent(events.Common.ApplicationStarted, func(e *application.ApplicationEvent) {
    fmt.Println("Application started")
})

// Application shutdown is NOT an event constant; register cleanup via:
app.OnShutdown(func() {
    fmt.Println("Application shutting down")
})

Методы диалоговых окон

Доступ к диалоговым окнам осуществляется через менеджер app.Dialog. Полное справочное руководство см. в разделе API диалоговых окон.

Диалоговые окна сообщений

// Information dialog
app.Dialog.Info().
    SetTitle("Success").
    SetMessage("Operation completed!").
    Show()

// Error dialog
app.Dialog.Error().
    SetTitle("Error").
    SetMessage("Something went wrong.").
    Show()

// Warning dialog
app.Dialog.Warning().
    SetTitle("Warning").
    SetMessage("This action cannot be undone.").
    Show()

Диалоговые окна вопросов

Для обработки ответов пользователя диалоговые окна вопросов используют функции обратного вызова кнопок:

dialog := app.Dialog.Question().
    SetTitle("Confirm").
    SetMessage("Continue?")

yes := dialog.AddButton("Yes")
yes.OnClick(func() {
    // Handle yes
})

no := dialog.AddButton("No")
no.OnClick(func() {
    // Handle no
})

dialog.SetDefaultButton(yes)
dialog.SetCancelButton(no)
dialog.Show()

Диалоговые окна выбора файлов

// Open file dialog
path, err := app.Dialog.OpenFile().
    SetTitle("Select File").
    AddFilter("Images", "*.png;*.jpg").
    PromptForSingleSelection()

// Save file dialog
path, err := app.Dialog.SaveFile().
    SetTitle("Save File").
    SetFilename("document.pdf").
    AddFilter("PDF", "*.pdf").
    PromptForSingleSelection()

// Folder selection (use OpenFile with directory options)
path, err := app.Dialog.OpenFile().
    SetTitle("Select Folder").
    CanChooseDirectories(true).
    CanChooseFiles(false).
    PromptForSingleSelection()

Журналирование

Приложение предоставляет логгер для структурированного журналирования:

app.Logger.Info("Message", "key", "value")
app.Logger.Error("Error occurred", "error", err)
app.Logger.Debug("Debug info")
app.Logger.Warn("Warning message")

Пример:

func (s *MyService) ProcessData(data string) error {
    s.app.Logger.Info("Processing data", "length", len(data))
    
    if err := process(data); err != nil {
        s.app.Logger.Error("Processing failed", "error", err)
        return err
    }
    
    s.app.Logger.Info("Processing complete")
    return nil
}

Обработка необработанных сообщений

Для приложений, которым требуется прямое низкоуровневое управление обменом данными между фронтендом и бэкендом, Wails предоставляет параметр RawMessageHandler. Он позволяет обойти стандартную систему привязок.

RawMessageHandler

RawMessageHandler — это поле структуры application.Options, а не метод. Среда выполнения вызывает его для каждого необработанного сообщения, отправленного из фронтенда через System.invoke().

type Options struct {
    // ... other fields ...
    RawMessageHandler func(window Window, message string, originInfo *OriginInfo)
}

OriginInfo содержит Origin, TopOrigin и IsMainFrame (на разных платформах заполняются разные подмножества полей — матрицу по платформам см. в руководстве по необработанным сообщениям).

Пример:

app := application.New(application.Options{
    Name: "My App",
    RawMessageHandler: func(window application.Window, message string, originInfo *application.OriginInfo) {
        // Handle the raw message
        fmt.Printf("Received from %s (%s): %s\n", window.Name(), originInfo.Origin, message)

        // You can respond using events
        window.EmitEvent("response", processMessage(message))
    },
})

Дополнительные сведения см. в руководстве по необработанным сообщениям.

Параметры для отдельных платформ

Параметры Windows

Настройте поведение для Windows на уровне приложения:

app := application.New(application.Options{
    Name: "My App",
    Windows: application.WindowsOptions{
        // WebView2 browser flags (apply to ALL windows)
        EnabledFeatures:       []string{"msWebView2EnableDraggableRegions"},
        DisabledFeatures:      []string{"msExperimentalFeature"},
        AdditionalBrowserArgs: []string{"--remote-debugging-port=9222"},

        // Other Windows options
        WndClass:                      "MyAppClass",
        WebviewUserDataPath:           "",  // Default: %APPDATA%\[BinaryName.exe]
        WebviewBrowserPath:            "",  // Default: system WebView2
        DisableQuitOnLastWindowClosed: false,
    },
})

Флаги браузера:

EnabledFeatures — включаемые флаги функций WebView2
DisabledFeatures — отключаемые флаги функций WebView2
AdditionalBrowserArgs — аргументы командной строки Chromium

Подробную документацию см. в разделе «Параметры окна — параметры Windows уровня приложения».

Параметры macOS

app := application.New(application.Options{
    Name: "My App",
    Mac: application.MacOptions{
        ActivationPolicy: application.ActivationPolicyRegular,
        ApplicationShouldTerminateAfterLastWindowClosed: true,
    },
})

Параметры Linux

app := application.New(application.Options{
    Name: "My App",
    Linux: application.LinuxOptions{
        ProgramName:                   "my-app",
        DisableQuitOnLastWindowClosed: false,
    },
})

Полный пример приложения

package main

import (
    "github.com/wailsapp/wails/v3/pkg/application"
)

func main() {
    app := application.New(application.Options{
        Name:        "My Application",
        Description: "A demo application",
        Mac: application.MacOptions{
            ApplicationShouldTerminateAfterLastWindowClosed: true,
        },
    })

    // Create main window
    window := app.Window.NewWithOptions(application.WebviewWindowOptions{
        Title:            "My App",
        Width:            1024,
        Height:           768,
        MinWidth:         800,
        MinHeight:        600,
        BackgroundColour: application.NewRGB(255, 255, 255),
        URL:              "http://wails.localhost/",
    })

    window.Center()
    window.Show()

    app.Run()
}

Специальные возможности

Редактировать эту документацию

API приложения

Обзор

Создание приложения

Основные методы

Run()

Quit()

Config()

Управление окнами

app.Window.New()

app.Window.NewWithOptions()

app.Window.GetByName()

app.Window.GetAll()

Менеджеры

Пример использования

Управление службами

RegisterService()

Управление событиями

app.Event.Emit()

app.Event.On()

app.Event.OnApplicationEvent()

Методы диалоговых окон

Диалоговые окна сообщений

Диалоговые окна вопросов

Диалоговые окна выбора файлов

Журналирование

Обработка необработанных сообщений

RawMessageHandler

Параметры для отдельных платформ

Параметры Windows

Параметры macOS

Параметры Linux

Полный пример приложения