Raccourcis globaux

Les raccourcis globaux sont des raccourcis clavier à l’échelle du système qui se déclenchent quelle que soit l’application ayant actuellement le focus, tant que votre application Wails est en cours d’exécution. Ils sont idéaux pour les raccourcis permettant d’afficher ou de masquer une fenêtre, les outils de capture rapide, les commandes multimédias et les autres fonctionnalités auxquelles les utilisateurs s’attendent à pouvoir accéder depuis n’importe où.

Les raccourcis globaux reposent directement sur les fonctionnalités natives de chaque plateforme et n’ajoutent aucune dépendance tierce.

Accéder au gestionnaire de raccourcis globaux

Le gestionnaire est disponible dans la propriété GlobalShortcut de votre instance d’application :

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

globalShortcuts := app.GlobalShortcut

Enregistrer un raccourci

Register accepte un accélérateur et une fonction de rappel. La fonction de rappel s’exécute dans sa propre goroutine chaque fois que le raccourci est pressé.

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

Vous pouvez enregistrer des raccourcis avant d’appeler app.Run. La liaison avec le système d’exploitation est alors effectuée automatiquement au démarrage de l’application.

Format des accélérateurs

Les raccourcis globaux utilisent le même format d’accélérateur que les accélérateurs de menu et les raccourcis clavier :

"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 correspond à Command sous macOS et à Control sous Windows et Linux, ce qui facilite la création de raccourcis multiplateformes.

Gérer les raccourcis

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

Tous les raccourcis enregistrés sont libérés automatiquement lorsque l’application se ferme ; vous n’avez donc pas besoin de les supprimer manuellement.

Que se passe-t-il lorsque le même raccourci est enregistré deux fois ?

Il existe deux cas distincts, que Wails gère différemment.

La même application enregistre deux fois un raccourci

Ce cas est géré par Wails lui-même et se comporte de manière identique sur toutes les plateformes. Le second appel à Register renvoie une erreur et la liaison d’origine reste en place (« erreur et conservation »). Ce comportement reste ainsi prévisible et signale l’erreur au lieu de remplacer silencieusement un raccourci fonctionnel.

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.

Pour modifier la fonction de rappel d’un raccourci, appelez d’abord Unregister pour ce raccourci, puis appelez à nouveau Register.

Une autre application détient déjà le raccourci

Ce cas est tranché par le système d’exploitation ; le résultat dépend donc de la plateforme :

Compte tenu de ces différences, vérifiez toujours l’erreur renvoyée par Register et prévoyez un raccourci de secours ou informez l’utilisateur lorsqu’un raccourci ne peut pas être réservé.

Considérations propres aux plateformes

Exemple complet

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