Electron 全局快捷键：globalShortcut 配置与按键映射
概述
Electron 的 globalShortcut 模块允许在应用程序窗口未获得焦点时，仍能响应系统级键盘快捷键。本节介绍快捷键的配置规范、按键映射关系以及最佳实践。
快捷键配置规范
Electron 官方文档提供了完整的 Accelerator（快捷键加速器）定义，涵盖所有可用的功能键和普通按键：
功能键
| 功能键 | 说明 |
|---|---|
Command / Cmd | macOS 专用 |
Control / Ctrl | Windows/Linux 标准 |
CommandOrControl | 跨平台自动映射 |
Alt | 在 macOS 上映射为 Option |
Shift | 上档键 |
Super / Meta | Windows 键 / macOS Cmd 键 |
普通按键
包括 0-9、A-Z、F1-F24 以及特殊键如 Plus、Space、Tab、Backspace、Delete、Insert、Return/Enter 等。
跨平台按键映射
| 组合键写法 | macOS | Windows/Linux |
|-------------------------------|----------------|----------------|
| CommandOrControl+X | Cmd+X | Ctrl+X |
| Alt+Shift+K | Option+Shift+K | Alt+Shift+K |
| Super+K | Cmd+K | Win+K |
text
globalShortcut API
在主进程中注册和管理系统级快捷键：
// electron/main.ts
import { app, globalShortcut, BrowserWindow } from 'electron'
app.whenReady().then(() => {
const win = new BrowserWindow({
width: 1200,
height: 800,
webPreferences: {
nodeIntegration: true,
contextIsolation: false,
},
})
win.loadFile('index.html')
// 注册全局快捷键
const registered = globalShortcut.register(
'CommandOrControl+Shift+K',
() => {
console.log('全局快捷键触发')
win.webContents.send('global-shortcut', 'CommandOrControl+Shift+K')
}
)
if (!registered) {
console.error('快捷键注册失败（可能被其他应用占用）')
}
// 注册多个快捷键
globalShortcut.registerAll(['MediaPlayPause', 'MediaNextTrack'], () => {
win.webContents.send('media-control')
})
})
// 应用退出时注销所有快捷键
app.on('will-quit', () => {
globalShortcut.unregisterAll()
})
typescript
API 方法一览
| 方法 | 说明 | 返回值 |
|---|---|---|
register(accelerator, callback) | 注册全局快捷键 | boolean |
registerAll(accelerators, callback) | 批量注册 | void |
isRegistered(accelerator) | 检查是否已注册 | boolean |
unregister(accelerator) | 注销指定快捷键 | void |
unregisterAll() | 注销所有快捷键 | void |
setSuspended(suspended) | 暂停/恢复所有快捷键 | void |
设计快捷键的最佳实践
- 形成肌肉记忆：参考 Photoshop、VS Code 等工具的快捷键设计理念，让用户通过左右手联动快速操作
- 建立用户粘性：当用户习惯了你的快捷键体系后，切换到同类软件会感到不顺手
- 提供快捷键映射：针对不同系统的用户习惯，允许自定义快捷键映射
- 避免冲突：不要占用系统级快捷键（如
Cmd+Space、Ctrl+Alt+Delete） - 清理资源：在
will-quit事件中务必调用unregisterAll()释放快捷键
注意事项
globalShortcut在主进程中配置，不在渲染进程中- 注册失败时返回
false，通常是因为快捷键已被其他应用占用 - Wayland 环境需启用
GlobalShortcutsPortal特性开关 - 全屏模式下，窗口控件行为可能受快捷键影响，需特殊处理
↑