Ereignissystem

Wails bietet ein einheitliches Ereignissystem für die Pub/Sub-Kommunikation. Lösen Sie Ereignisse überall aus und empfangen Sie sie überall – von Go zu JavaScript, von JavaScript zu Go und von Fenster zu Fenster. Dies ermöglicht eine entkoppelte Architektur mit typisierten Ereignissen und Lebenszyklus-Hooks.

Schnelleinstieg

Go (auslösen):

app.Event.Emit("user-logged-in", map[string]interface{}{
    "userId": 123,
    "name": "Alice",
})

JavaScript (empfangen):

javascript

import { Events } from '@wailsio/runtime'

Events.On("user-logged-in", (event) => {
    console.log(`User ${event.data.name} logged in`)
})

Das ist alles! Sprachübergreifendes Pub/Sub.

Ereignistypen

Benutzerdefinierte Ereignisse

Anwendungsspezifische Ereignisse:

// Emit from Go
app.Event.Emit("order-created", order)
app.Event.Emit("payment-processed", payment)
app.Event.Emit("notification", message)

javascript

// Listen in JavaScript
Events.On("order-created", handleOrder)
Events.On("payment-processed", handlePayment)
Events.On("notification", showNotification)

Systemereignisse

Integrierte Betriebssystem- und Anwendungsereignisse:

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

// Theme changes
app.Event.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
    if e.Context().IsDarkMode() {
        app.Logger.Info("Dark mode enabled")
    }
})

// Application lifecycle
app.Event.OnApplicationEvent(events.Common.ApplicationStarted, func(e *application.ApplicationEvent) {
    app.Logger.Info("Application started")
})

Fensterereignisse

Fensterspezifische Ereignisse:

window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window focused")
})

window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
    app.Logger.Info("Window closing")
})

Ereignisse auslösen

Aus Go

Einfaches Auslösen:

app.Event.Emit("event-name", data)

Mit verschiedenen Datentypen:

// String
app.Event.Emit("message", "Hello")

// Number
app.Event.Emit("count", 42)

// Struct
app.Event.Emit("user", User{ID: 1, Name: "Alice"})

// Map
app.Event.Emit("config", map[string]interface{}{
    "theme": "dark",
    "fontSize": 14,
})

// Array
app.Event.Emit("items", []string{"a", "b", "c"})

Für ein bestimmtes Fenster:

window.EmitEvent("window-specific-event", data)

Aus JavaScript

javascript

import { Events } from '@wailsio/runtime'

// Emit to Go
Events.Emit("button-clicked", { buttonId: "submit" })

// Emit to all windows
Events.Emit("broadcast-message", "Hello everyone")

Ereignisse empfangen

In Go

Anwendungsereignisse:

app.Event.On("custom-event", func(e *application.CustomEvent) {
    data := e.Data
    // Handle event
})

Mit Typzusicherung:

app.Event.On("user-updated", func(e *application.CustomEvent) {
    user := e.Data.(User)
    app.Logger.Info("User updated", "name", user.Name)
})

Mehrere Handler:

// All handlers will be called
app.Event.On("order-created", logOrder)
app.Event.On("order-created", sendEmail)
app.Event.On("order-created", updateInventory)

In JavaScript

Einfacher Listener:

javascript

import { Events } from '@wailsio/runtime'

Events.On("event-name", (event) => {
    console.log("Event received:", event.data)
})

Mit Bereinigung:

javascript

const unsubscribe = Events.On("event-name", handleEvent)

// Later, stop listening
unsubscribe()

Mehrere Handler:

javascript

Events.On("data-updated", updateUI)
Events.On("data-updated", saveToCache)
Events.On("data-updated", logChange)

Einmalig ausgeführte Handler:

javascript

Events.Once("data-updated", updateVariable)

Systemereignisse

Anwendungsereignisse

Allgemeine Ereignisse (plattformübergreifend):

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

// Application started
app.Event.OnApplicationEvent(events.Common.ApplicationStarted, func(e *application.ApplicationEvent) {
    app.Logger.Info("App started")
})

// Theme changed
app.Event.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
    isDark := e.Context().IsDarkMode()
    app.Event.Emit("theme-changed", isDark)
})

// System about to suspend
app.Event.OnApplicationEvent(events.Common.SystemWillSleep, func(e *application.ApplicationEvent) {
    flushPendingWrites()
})

// System resumed from suspend
app.Event.OnApplicationEvent(events.Common.SystemDidWake, func(e *application.ApplicationEvent) {
    reconnectSockets()
    refreshState()
})

// File opened
app.Event.OnApplicationEvent(events.Common.ApplicationOpenedWithFile, func(e *application.ApplicationEvent) {
    // Single-file: e.Context().Filename() returns ""; for multi-file launches
    // (Finder "Open With..." → multiple selection) use OpenedFiles().
    filePath := e.Context().Filename()
    openFile(filePath)
})

Plattformspezifische Ereignisse:

// Application became active
app.Event.OnApplicationEvent(events.Mac.ApplicationDidBecomeActive, func(e *application.ApplicationEvent) {
    app.Logger.Info("App became active")
})

// Application will terminate
app.Event.OnApplicationEvent(events.Mac.ApplicationWillTerminate, func(e *application.ApplicationEvent) {
    cleanup()
})

// System about to sleep / resumed
app.Event.OnApplicationEvent(events.Mac.ApplicationWillSleep, func(e *application.ApplicationEvent) {
    flushPendingWrites()
})
app.Event.OnApplicationEvent(events.Mac.ApplicationDidWake, func(e *application.ApplicationEvent) {
    refreshState()
})

// Displays sleeping/waking — distinct from system sleep (e.g. lid lowered)
app.Event.OnApplicationEvent(events.Mac.ApplicationScreensDidSleep, func(e *application.ApplicationEvent) {
    pauseRendering()
})
app.Event.OnApplicationEvent(events.Mac.ApplicationScreensDidWake, func(e *application.ApplicationEvent) {
    resumeRendering()
})

// Power status changed
app.Event.OnApplicationEvent(events.Windows.APMPowerStatusChange, func(e *application.ApplicationEvent) {
    app.Logger.Info("Power status changed")
})

// System suspending
app.Event.OnApplicationEvent(events.Windows.APMSuspend, func(e *application.ApplicationEvent) {
    saveState()
})

// System resumed. APMResumeAutomatic always fires on resume;
// APMResumeSuspend fires after it when the wake was triggered by
// user input. Prefer Common.SystemDidWake if you don't need to
// distinguish.
app.Event.OnApplicationEvent(events.Windows.APMResumeAutomatic, func(e *application.ApplicationEvent) {
    refreshState()
})

// Application startup
app.Event.OnApplicationEvent(events.Linux.ApplicationStartup, func(e *application.ApplicationEvent) {
    app.Logger.Info("App starting")
})

// Theme changed
app.Event.OnApplicationEvent(events.Linux.SystemThemeChanged, func(e *application.ApplicationEvent) {
    updateTheme()
})

// System sleep/wake — sourced from systemd-logind's PrepareForSleep
// signal on the system bus. Requires logind/elogind exposing
// org.freedesktop.login1, so it may be unavailable on distros/setups
// without it (Alpine, Void, some Devuan setups).
app.Event.OnApplicationEvent(events.Linux.SystemWillSleep, func(e *application.ApplicationEvent) {
    flushPendingWrites()
})
app.Event.OnApplicationEvent(events.Linux.SystemDidWake, func(e *application.ApplicationEvent) {
    refreshState()
})

Fensterereignisse

Allgemeine Fensterereignisse:

// Window focus
window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window focused")
})

// Window blur
window.OnWindowEvent(events.Common.WindowLostFocus, func(e *application.WindowEvent) {
    app.Logger.Info("Window blurred")
})

// Window closing
window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if hasUnsavedChanges() {
        e.Cancel()  // Prevent close
    }
})

// Window closed
window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
    cleanup()
})

Ereignis-Hooks

Hooks werden vor Standard-Listenern ausgeführt und können Ereignisse abbrechen:

// Hook - runs first, can cancel
window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
    if hasUnsavedChanges() {
        result := showConfirmdialog("Unsaved changes. Close anyway?")
        if result != "yes" {
            e.Cancel()  // Prevent window close
        }
    }
})

// Standard listener - runs after hooks
window.OnWindowEvent(events.Common.WindowClosing, func(e *application.WindowEvent) {
    app.Logger.Info("Window closing")
})

Wesentliche Unterschiede:

Merkmal	Hooks	Standard-Listener
Ausführungsreihenfolge	Zuerst, in Registrierungsreihenfolge	Nach den Hooks, keine garantierte Reihenfolge
Blockierung	Synchron, blockiert den nächsten Hook	Asynchron, nicht blockierend
Kann abbrechen	Ja	Nein (bereits weitergegeben)
Anwendungsfall	Ablaufsteuerung, Validierung	Protokollierung, Seiteneffekte

Ereignismuster

Pub/Sub-Muster

// Publisher (service)
type OrderService struct {
    app *application.App
}

func (o *OrderService) CreateOrder(items []Item) (*Order, error) {
    order := &Order{Items: items}
    
    if err := o.saveOrder(order); err != nil {
        return nil, err
    }
    
    // Publish event
    o.app.Event.Emit("order-created", order)
    
    return order, nil
}

// Subscribers
app.Event.On("order-created", func(e *application.CustomEvent) {
    order := e.Data.(*Order)
    sendConfirmationEmail(order)
})

app.Event.On("order-created", func(e *application.CustomEvent) {
    order := e.Data.(*Order)
    updateInventory(order)
})

app.Event.On("order-created", func(e *application.CustomEvent) {
    order := e.Data.(*Order)
    logOrder(order)
})

Request/Response-Muster

// Frontend requests data
Emit("get-user-data", { userId: 123 })

// Backend responds
app.Event.On("get-user-data", func(e *application.CustomEvent) {
    data := e.Data.(map[string]interface{})
    userId := int(data["userId"].(float64))
    
    user := getUserFromDB(userId)
    
    // Send response
    app.Event.Emit("user-data-response", user)
})

javascript

// Frontend receives response
Events.On("user-data-response", (event) => {
    const user = event.data
    displayUser(user)
})

Hinweis: Für Request/Response sind Bindings besser geeignet. Verwenden Sie Ereignisse für Benachrichtigungen.

Broadcast-Muster

// Broadcast to all windows
app.Event.Emit("global-notification", "System update available")

// Each window handles it
Events.On("global-notification", (event) => {
    const message = event.data
    showNotification(message)
})

Ereignisaggregation

type EventAggregator struct {
    events []Event
    mu     sync.Mutex
}

func (ea *EventAggregator) Add(event Event) {
    ea.mu.Lock()
    defer ea.mu.Unlock()
    
    ea.events = append(ea.events, event)
    
    // Emit batch every 100 events
    if len(ea.events) >= 100 {
        app.Event.Emit("event-batch", ea.events)
        ea.events = nil
    }
}

Vollständiges Beispiel

Go:

package main

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

type NotificationService struct {
    app *application.App
}

func (n *NotificationService) Notify(message string) {
    // Emit to all windows
    n.app.Event.Emit("notification", map[string]interface{}{
        "message":   message,
        "timestamp": time.Now(),
    })
}

func main() {
    app := application.New(application.Options{
        Name: "Event Demo",
    })
    
    notifService := &NotificationService{app: app}
    
    // System events
    app.Event.OnApplicationEvent(events.Common.ThemeChanged, func(e *application.ApplicationEvent) {
        isDark := e.Context().IsDarkMode()
        app.Event.Emit("theme-changed", isDark)
    })
    
    // Custom events from frontend
    app.Event.On("user-action", func(e *application.CustomEvent) {
        data := e.Data.(map[string]interface{})
        action := data["action"].(string)
        
        app.Logger.Info("User action", "action", action)
        
        // Respond
        notifService.Notify("Action completed: " + action)
    })
    
    // Window events
    window := app.Window.New()
    
    window.OnWindowEvent(events.Common.WindowFocus, func(e *application.WindowEvent) {
        app.Event.Emit("window-focused", window.Name())
    })
    
    window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
        // Confirm before close
        app.Event.Emit("confirm-close", nil)
        e.Cancel()  // Wait for confirmation
    })
    
    app.Run()
}

JavaScript:

javascript

import { Events } from '@wailsio/runtime'

// Listen for notifications
Events.On("notification", (event) => {
    showNotification(event.data.message)
})

// Listen for theme changes
Events.On("theme-changed", (event) => {
    const isDark = event.data
    document.body.classList.toggle('dark', isDark)
})

// Listen for window focus
Events.On("window-focused", (event) => {
    const windowName = event.data
    console.log(`Window ${windowName} focused`)
})

// Handle close confirmation
Events.On("confirm-close", (event) => {
    if (confirm("Close window?")) {
        Events.Emit("close-confirmed", true)
    }
})

// Emit user actions
document.getElementById('button').addEventListener('click', () => {
    Events.Emit("user-action", { action: "button-clicked" })
})

Bewährte Vorgehensweisen

✅ Empfohlen

Ereignisse für Benachrichtigungen verwenden – unidirektionale Kommunikation
Bindings für Anfragen verwenden – bidirektionale Kommunikation
Ereignisnamen konsistent halten – kebab-case verwenden
Ereignisdaten dokumentieren – welche Felder sind enthalten?
Nicht mehr benötigte Abonnements kündigen – Speicherlecks vermeiden
Hooks zur Validierung verwenden – den Ereignisfluss steuern

❌ Nicht empfohlen

Ereignisse nicht für RPC verwenden – stattdessen Bindings verwenden
Nicht zu häufig auslösen – bei Bedarf bündeln
Handler nicht blockieren – schnell ausführen
Abmeldung nicht vergessen – sonst drohen Speicherlecks
Ereignisse nicht für große Datenmengen verwenden – stattdessen Bindings verwenden
Keine Ereignisschleifen erzeugen – A löst B aus, B löst A aus

Nächste Schritte

Leitfaden zu Ereignissen

Erfahren Sie mehr über Ereignismuster und die typsichere Ereignisgenerierung.

Mehr erfahren →

Ereignis-API

Entdecken Sie die vollständige API für Anwendungs- und Fensterereignisse.

Mehr erfahren →

Bindings

Verwenden Sie Bindings für Anfrage und Antwort.

Mehr erfahren →

Fensterereignisse

Verarbeiten Sie Ereignisse im Lebenszyklus von Fenstern.

Mehr erfahren →

Fragen? Stellen Sie sie auf Discord oder sehen Sie sich die Ereignisbeispiele an.

Barrierefreiheit

Diese Dokumentation bearbeiten

Ereignissystem

Ereignissystem

Schnelleinstieg

Ereignistypen

Benutzerdefinierte Ereignisse

Systemereignisse

Fensterereignisse

Ereignisse auslösen

Aus Go

Aus JavaScript

Ereignisse empfangen

In Go

In JavaScript

Systemereignisse

Anwendungsereignisse

Fensterereignisse

Ereignis-Hooks

Ereignismuster

Pub/Sub-Muster

Request/Response-Muster

Broadcast-Muster

Ereignisaggregation

Vollständiges Beispiel

Bewährte Vorgehensweisen

✅ Empfohlen

❌ Nicht empfohlen

Nächste Schritte