Pintasan Global

Pintasan global adalah pintasan papan ketik di seluruh sistem yang dipicu tanpa bergantung pada aplikasi mana yang sedang memiliki fokus, selama aplikasi Wails Anda berjalan. Pintasan ini ideal untuk tombol pintas tampilkan/sembunyikan, alat tangkap cepat, kontrol media, dan fitur lain yang diharapkan pengguna dapat diakses dari mana saja.

Pintasan global dibangun langsung di atas fasilitas native setiap platform dan tidak menambahkan dependensi pihak ketiga.

Mengakses Pengelola Pintasan Global

Pengelola tersedia melalui properti GlobalShortcut pada instans aplikasi Anda:

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

globalShortcuts := app.GlobalShortcut

Mendaftarkan Pintasan

Register menerima akselerator dan callback. Callback berjalan dalam goroutine tersendiri setiap kali pintasan ditekan.

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

Anda dapat mendaftarkan pintasan sebelum memanggil app.Run. Pengikatan dengan sistem operasi kemudian dilakukan secara otomatis saat aplikasi dimulai.

Format Akselerator

Pintasan global menggunakan format akselerator yang sama dengan akselerator menu dan pengikatan tombol:

"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 ditetapkan menjadi Command di macOS serta Control di Windows dan Linux, sehingga praktis digunakan untuk pintasan lintas platform.

Mengelola Pintasan

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

Semua pintasan yang terdaftar dilepas secara otomatis saat aplikasi keluar, sehingga Anda tidak perlu membersihkannya secara manual.

Yang Terjadi Saat Pintasan yang Sama Didaftarkan Dua Kali

Ada dua kasus yang berbeda, dan Wails menanganinya secara berbeda.

Aplikasi yang sama mendaftarkan pintasan dua kali

Kasus ini ditangani oleh Wails sendiri dan berperilaku identik di setiap platform. Pemanggilan Register yang kedua mengembalikan kesalahan dan pengikatan semula tetap dipertahankan (“kesalahan dan pertahankan”). Hal ini menjaga perilaku tetap dapat diprediksi dan menampilkan kesalahan tersebut alih-alih secara diam-diam mengganti pintasan yang berfungsi.

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.

Jika ingin mengubah callback untuk suatu pintasan, Unregister pintasan tersebut terlebih dahulu, lalu Register kembali.

Aplikasi lain sudah memiliki pintasan tersebut

Kasus ini ditentukan oleh sistem operasi, sehingga hasilnya bergantung pada platform:

Karena perbedaan ini, selalu periksa kesalahan yang dikembalikan oleh Register dan sediakan pintasan alternatif atau umpan balik bagi pengguna ketika suatu pintasan tidak dapat diklaim.

Pertimbangan Platform

Contoh Lengkap

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