Глобальные сочетания клавиш

Глобальные сочетания клавиш — это общесистемные сочетания, которые срабатывают независимо от того, какое приложение сейчас находится в фокусе, пока запущено ваше приложение Wails. Они идеально подходят для горячих клавиш показа и скрытия, инструментов быстрого захвата, управления мультимедиа и других функций, которые должны быть доступны пользователям отовсюду.

Глобальные сочетания клавиш реализованы непосредственно на основе нативных возможностей каждой платформы и не добавляют сторонних зависимостей.

Доступ к диспетчеру глобальных сочетаний клавиш

Диспетчер доступен через свойство GlobalShortcut экземпляра вашего приложения:

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

globalShortcuts := app.GlobalShortcut

Регистрация сочетания клавиш

Register принимает акселератор и функцию обратного вызова. При каждом нажатии сочетания функция обратного вызова выполняется в отдельной горутине.

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

Сочетания клавиш можно регистрировать до вызова app.Run. В этом случае привязка в операционной системе выполняется автоматически при запуске приложения.

Формат акселератора

Для глобальных сочетаний клавиш используется тот же формат акселераторов, что и для акселераторов меню и привязок клавиш:

"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 соответствует Command в macOS и Control в Windows и Linux, что удобно для кроссплатформенных сочетаний клавиш.

Управление сочетаниями клавиш

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

При завершении работы приложения все зарегистрированные сочетания клавиш освобождаются автоматически, поэтому удалять их вручную не нужно.

Что происходит при двукратной регистрации одного сочетания клавиш

Есть два разных случая, которые Wails обрабатывает по-разному.

Одно приложение дважды регистрирует сочетание клавиш

Этот случай обрабатывает сам Wails, и поведение одинаково на всех платформах. Второй вызов Register возвращает ошибку, а исходная привязка сохраняется («ошибка с сохранением»). Благодаря этому поведение остаётся предсказуемым, а ошибка становится явной вместо незаметной замены рабочего сочетания клавиш.

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.

Чтобы изменить функцию обратного вызова для сочетания клавиш, сначала выполните для него Unregister, а затем снова Register.

Сочетание клавиш уже занято другим приложением

Решение принимает операционная система, поэтому результат зависит от платформы:

Из-за этих различий всегда проверяйте ошибку, возвращаемую Register, и предусмотрите запасное сочетание клавиш или уведомление пользователя на случай, если зарегистрировать сочетание не удастся.

Особенности платформ

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

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