Tauri v2에서 전역 키보드 단축키 — 올바른 방법과 잘못된 방법

Source: Dev.to

모든 테스트는 8년 된 MacBook Air에서 실행되었습니다.
7개의 Mac 앱을 솔로 개발자로 배포한 결과입니다. 스폰서된 의견이 아닙니다.

기본

플러그인 추가:

# Cargo.toml
tauri-plugin-global-shortcut = "2"

// package.json
"@tauri-apps/plugin-global-shortcut": "^2.0.0"

main.rs에 등록:

use tauri_plugin_global_shortcut::{Code, GlobalShortcutExt, Modifiers, Shortcut};

tauri::Builder::default()
    .plugin(tauri_plugin_global_shortcut::Builder::new().build())
    .setup(|app| {
        let shortcut = Shortcut::new(
            Some(Modifiers::SUPER | Modifiers::SHIFT),
            Code::KeyH,
        );
        app.global_shortcut().register(shortcut)?;
        Ok(())
    })

잘못된 방법: 하드코딩된 단축키

Cmd+Shift+H를 하드코딩하면 내 컴퓨터에서는 동작하지만, 이미 해당 단축키를 시스템에서 사용 중인 사용자에게는 충돌이 발생합니다. 대신 단축키를 설정 가능하게 만들고, 사용자의 선호도를 저장한 뒤 실행 시에 등록하세요(사용자가 변경하면 다시 등록).

let stored = get_shortcut_from_prefs(); // SQLite 또는 설정 파일에서 읽음
app.global_shortcut().register(stored)?;

macOS 권한 현실

macOS에서는 앱이 포커스에 있지 않을 때 전역 단축키에 접근성(Accessibility) 권한이 필요합니다. 일반적인 흐름:

1. 사용자가 앱을 설치합니다.
2. 전역 단축키를 처음 사용할 때 아무 일도 일어나지 않습니다.
3. 사용자는 단축키가 작동하지 않는다고 생각합니다.

해결 방법: 실행 시 접근성 권한을 확인하고, 권한이 없으면 사용자에게 요청하세요. 프론트엔드에 이벤트를 보내 UI가 시스템 설정 > 개인정보 보호 > 접근성으로 안내하도록 합니다.

// 설정 단계에서 단축키를 등록한 뒤
// 권한이 없을 경우 프론트엔드에 이벤트를 전송
// UI가 사용자를 시스템 설정 > 개인정보 보호 > 접근성으로 안내하도록 함

앱 종료 시 단축키 해제

Tauri v2는 앱이 종료될 때 자동으로 단축키를 정리합니다. 사용자가 설정을 변경해 동적으로 단축키를 다시 등록하는 경우, 먼저 기존 단축키를 해제하세요:

app.global_shortcut().unregister(old_shortcut)?;
app.global_shortcut().register(new_shortcut)?;

두 번 등록된 단축키는 일부 macOS 버전에서 조용히 실패할 수 있습니다.

결론

Tauri v2의 전역 단축키는 잘 동작하고 플러그인 API도 깔끔합니다. 주요 함정 두 가지는 다음과 같습니다:

• 사용자 정의 단축키와 충돌할 수 있는 하드코딩된 단축키.
• 접근성 권한 흐름을 놓치는 경우.

첫 번째 릴리스를 앞두고 설정 가능하도록 구현하고 권한 처리를 반드시 포함하세요.

유용했다면 ❤️ 하나가 생각보다 큰 도움이 됩니다 — 감사합니다!

Hiyoko PDF Vault →
X →