Globale Tastenkürzel

Globale Tastenkürzel sind systemweite Tastenkombinationen, die unabhängig davon ausgelöst werden, welche Anwendung gerade den Fokus hat, solange Ihre Wails-Anwendung ausgeführt wird. Sie eignen sich ideal für Tastenkürzel zum Ein- und Ausblenden, Werkzeuge zur Schnellerfassung, Mediensteuerungen und andere Funktionen, auf die Benutzer von überall aus zugreifen möchten.

Globale Tastenkürzel basieren direkt auf den nativen Funktionen der jeweiligen Plattform und fügen keine Abhängigkeiten von Drittanbietern hinzu.

Auf den Manager für globale Tastenkürzel zugreifen

Der Manager ist über die Eigenschaft GlobalShortcut Ihrer Anwendungsinstanz verfügbar:

app := application.New(application.Options{
    Name: "Global Shortcuts Demo",
})

globalShortcuts := app.GlobalShortcut

Ein Tastenkürzel registrieren

Register erwartet einen Accelerator und einen Callback. Der Callback wird bei jedem Drücken des Tastenkürzels in einer eigenen Goroutine ausgeführt.

err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+G", func() {
    // Runs even when another application is focused.
    window.Show()
    window.Focus()
})
if err != nil {
    app.Logger.Error("could not register shortcut", "error", err)
}

Sie können Tastenkürzel registrieren, bevor Sie app.Run aufrufen. Die Bindung an das Betriebssystem erfolgt dann automatisch beim Start der Anwendung.

Accelerator-Format

Globale Tastenkürzel verwenden dasselbe Accelerator-Format wie Menü-Accelerators und Tastenbelegungen:

"CmdOrCtrl+Shift+G"  // Command on macOS, Control elsewhere
"Ctrl+Alt+K"         // Control + Alt + K
"Cmd+Option+Space"   // Command + Option + Space (macOS)
"Super+D"            // Super / Windows / Logo key + D
"Ctrl+Shift+F5"      // Function keys are supported

CmdOrCtrl wird unter macOS zu Command und unter Windows und Linux zu Control aufgelöst, was plattformübergreifende Tastenkürzel vereinfacht.

Tastenkürzel verwalten

// Check whether a shortcut is registered (modifier order does not matter).
registered := app.GlobalShortcut.IsRegistered("Ctrl+Shift+G")

// List every shortcut this application has registered.
for _, accelerator := range app.GlobalShortcut.GetAll() {
    app.Logger.Info("global shortcut", "accelerator", accelerator)
}

// Release a single shortcut.
app.GlobalShortcut.Unregister("Ctrl+Shift+G")

// Release everything (also done automatically on shutdown).
app.GlobalShortcut.UnregisterAll()

Alle registrierten Tastenkürzel werden beim Beenden der Anwendung automatisch freigegeben. Sie müssen sie daher nicht manuell bereinigen.

Was geschieht, wenn dasselbe Tastenkürzel zweimal registriert wird?

Es gibt zwei unterschiedliche Fälle, die Wails verschieden behandelt.

Dieselbe Anwendung registriert ein Tastenkürzel zweimal

Wails löst diesen Fall selbst auf und verhält sich dabei auf jeder Plattform identisch. Der zweite Aufruf von Register gibt einen Fehler zurück, und die ursprüngliche Bindung bleibt bestehen („Fehler melden und beibehalten“). Dadurch bleibt das Verhalten vorhersehbar und der Fehler wird sichtbar, statt ein funktionierendes Tastenkürzel unbemerkt zu ersetzen.

app.GlobalShortcut.Register("Ctrl+Shift+G", showWindow)        // ok
err := app.GlobalShortcut.Register("Shift+Ctrl+G", doSomething) // err: already registered
// showWindow is still the active callback for this shortcut.

Wenn Sie den Callback eines Tastenkürzels ändern möchten, führen Sie dafür zuerst Unregister und anschließend erneut Register aus.

Eine andere Anwendung besitzt das Tastenkürzel bereits

Darüber entscheidet das Betriebssystem, weshalb das Ergebnis plattformspezifisch ist:

Prüfen Sie wegen dieser Unterschiede stets den von Register zurückgegebenen Fehler. Stellen Sie außerdem ein alternatives Tastenkürzel bereit oder informieren Sie den Benutzer, wenn ein Tastenkürzel nicht beansprucht werden kann.

Plattformspezifische Hinweise

Vollständiges Beispiel

package main

import (
    "log"

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

func main() {
    app := application.New(application.Options{
        Name: "Global Shortcuts Demo",
    })

    window := app.Window.New()

    // Bring the window to the front from anywhere.
    if err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+G", func() {
        window.Show()
        window.Focus()
    }); err != nil {
        log.Printf("could not register show shortcut: %v", err)
    }

    // Hide the window from anywhere.
    if err := app.GlobalShortcut.Register("CmdOrCtrl+Shift+H", func() {
        window.Hide()
    }); err != nil {
        log.Printf("could not register hide shortcut: %v", err)
    }

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