검색
기여하기

이 문서 편집

문서를 번역하거나 컴퓨터에서 전체 프로젝트를 여세요.

작업을 제출하기 전까지는 아무것도 게시되지 않습니다.

전역 단축키

애플리케이션에 포커스가 없을 때도 작동하는 시스템 전역 키보드 단축키를 등록합니다

전역 단축키는 Wails 애플리케이션이 실행되는 동안 현재 어떤 애플리케이션에 포커스가 있는지와 관계없이 작동하는 시스템 전역 키보드 단축키입니다. 표시/숨기기 단축키, 빠른 캡처 도구, 미디어 제어 기능처럼 사용자가 어디서나 이용할 수 있기를 기대하는 기능에 적합합니다.

전역 단축키는 각 플랫폼의 네이티브 기능을 직접 기반으로 구현되며 서드 파티 종속성을 추가하지 않습니다.

전역 단축키 관리자에 접근하기

애플리케이션 인스턴스의 GlobalShortcut 속성을 통해 관리자에 접근할 수 있습니다.

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

globalShortcuts := app.GlobalShortcut

단축키 등록하기

Register은 액셀러레이터와 콜백을 인수로 받습니다. 단축키를 누를 때마다 콜백이 별도의 고루틴에서 실행됩니다.

go
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을 호출하기 전에 단축키를 등록할 수 있습니다. 그러면 애플리케이션이 시작될 때 운영 체제와의 바인딩이 자동으로 수행됩니다.

액셀러레이터 형식

전역 단축키는 메뉴 액셀러레이터 및 키 바인딩과 같은 액셀러레이터 형식을 사용합니다.

go
"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은 macOS에서는 Command로, Windows와 Linux에서는 Control로 해석되므로 크로스 플랫폼 단축키를 편리하게 정의할 수 있습니다.

단축키 관리하기

go
// 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 호출은 오류를 반환하고 기존 바인딩은 그대로 유지됩니다(“오류를 반환하고 유지”). 따라서 작동 중인 단축키를 조용히 대체하는 대신 실수를 드러내어 예측 가능한 동작을 유지합니다.

go
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하세요.

다른 애플리케이션이 이미 단축키를 소유한 경우

이 경우는 운영 체제가 결정하므로 결과는 플랫폼별로 다릅니다.

플랫폼 다른 애플리케이션이 단축키를 소유한 경우의 동작
macOS 등록에 성공합니다. macOS에서는 여러 애플리케이션이 같은 단축키를 등록할 수 있으므로 등록이 거부되지 않고 기존 소유자의 콜백과 함께 애플리케이션의 콜백이 추가됩니다.
Windows 등록에 실패하고 Register이 오류를 반환합니다. 단축키를 먼저 등록한 애플리케이션이 계속 소유합니다.
Linux (X11) X 서버가 같은 키 조합의 두 번째 그랩을 거부하므로 등록에 실패하고 Register이 오류를 반환합니다.
Linux (Wayland) 컴포지터가 조정합니다. 일반적으로 사용자에게 데스크톱의 전역 단축키 대화 상자를 통해 바인딩을 승인하거나 선택하라는 메시지가 표시됩니다.

이러한 차이가 있으므로 항상 Register이 반환하는 오류를 확인하고, 단축키를 확보할 수 없을 때는 대체 단축키를 제공하거나 사용자에게 피드백을 표시하세요.

플랫폼별 고려 사항

전역 단축키는 Carbon Event Manager의 단축키 API를 사용합니다. 이는 macOS에서 시스템 전역 단축키를 구현하는 표준 메커니즘이며 손쉬운 사용 권한이 필요하지 않습니다.

단축키는 키의 물리적 위치에 바인딩되므로 QWERTY가 아닌 레이아웃에서도 표준 ANSI/QWERTY 위치의 키에 매핑됩니다.

전체 예제

go
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)
    }
}
페이지 편집

마지막 업데이트: