API Application

Vue d’ensemble

L’Application est au cœur de votre application Wails. Elle gère les fenêtres, les services et les événements, et donne accès à toutes les fonctionnalités de la plateforme.

Création d’une application

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{}),
    },
})

Méthodes principales

Run()

Démarre la boucle d’événements de l’application.

func (a *App) Run() error

Exemple :

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

Valeur renvoyée : une erreur si le démarrage échoue

Quit()

Arrête proprement l’application.

func (a *App) Quit()

Exemple :

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

Config()

Renvoie la configuration de l’application.

func (a *App) Config() Options

Exemple :

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

Gestion des fenêtres

app.Window.New()

Crée une fenêtre webview avec les options par défaut.

func (wm *WindowManager) New() *WebviewWindow

Exemple :

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

app.Window.NewWithOptions()

Crée une fenêtre webview avec des options personnalisées.

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

Exemple :

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

app.Window.GetByName()

Obtient une fenêtre à partir de son nom. Renvoie la fenêtre et indique si elle a été trouvée.

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

Exemple :

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

app.Window.GetAll()

Renvoie toutes les fenêtres de l’application.

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

Exemple :

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

Gestionnaires

L’Application donne accès à différents gestionnaires au moyen de propriétés :

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

Exemple d’utilisation

// 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()

Gestion des services

RegisterService()

Enregistre un service auprès de l’application.

func (a *App) RegisterService(service Service)

RegisterService ne renvoie rien ; les erreurs d’initialisation du service se manifestent par des échecs de ServiceStartup pendant app.Run().

Exemple :

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)))

Gestion des événements

app.Event.Emit()

Émet un événement personnalisé. Renvoie true si un hook a annulé l’émission.

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

Exemple :

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

app.Event.On()

Écoute les événements personnalisés. Renvoie une fonction func() de désabonnement.

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

Exemple :

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()

Écoute les événements du cycle de vie de l’application. Le paramètre eventType est de type events.ApplicationEventType (issu du package events).

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

Exemple :

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")
})

Méthodes de boîte de dialogue

Les boîtes de dialogue sont accessibles au moyen du gestionnaire app.Dialog. Consultez l’API des boîtes de dialogue pour obtenir la référence complète.

Boîtes de dialogue de message

// 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()

Boîtes de dialogue de question

Les boîtes de dialogue de question utilisent des fonctions de rappel associées aux boutons pour traiter les réponses de l’utilisateur :

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()

Boîtes de dialogue de fichiers

// 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()

Journalisation

L’application fournit un journaliseur structuré :

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

Exemple :

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
}

Traitement des messages bruts

Pour les applications qui nécessitent un contrôle direct et de bas niveau sur la communication entre le frontend et le backend, Wails fournit l’option RawMessageHandler. Celle-ci contourne le système de liaison standard.

RawMessageHandler

RawMessageHandler est un champ de application.Options, et non une méthode. Le runtime l’appelle pour chaque message brut envoyé depuis le frontend au moyen de System.invoke().

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

OriginInfo transporte Origin, TopOrigin et IsMainFrame (les plateformes renseignent des sous-ensembles différents — consultez le guide des messages bruts pour connaître la matrice propre à chaque plateforme).

Exemple :

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))
    },
})

Pour plus de détails, consultez le guide des messages bruts.

Options propres à chaque plateforme

Options Windows

Configurez le comportement propre à Windows au niveau de l’application :

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,
    },
})

Indicateurs du navigateur :

EnabledFeatures — indicateurs de fonctionnalités WebView2 à activer
DisabledFeatures — indicateurs de fonctionnalités WebView2 à désactiver
AdditionalBrowserArgs - Arguments de ligne de commande Chromium

Consultez Options de fenêtre - Options Windows au niveau de l’application pour obtenir une documentation détaillée.

Options macOS

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

Options Linux

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

Exemple d’application complet

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()
}

Accessibilité

Modifier cette documentation

API Application

Vue d’ensemble

Création d’une application

Méthodes principales

Run()

Quit()

Config()

Gestion des fenêtres

app.Window.New()

app.Window.NewWithOptions()

app.Window.GetByName()

app.Window.GetAll()

Gestionnaires

Exemple d’utilisation

Gestion des services

RegisterService()

Gestion des événements

app.Event.Emit()

app.Event.On()

app.Event.OnApplicationEvent()

Méthodes de boîte de dialogue

Boîtes de dialogue de message

Boîtes de dialogue de question

Boîtes de dialogue de fichiers

Journalisation

Traitement des messages bruts

RawMessageHandler

Options propres à chaque plateforme

Options Windows

Options macOS

Options Linux

Exemple d’application complet