键盘快捷键¶

加速器¶

加速器是可用于在整个 Electron 应用中表示键盘快捷键的字符串。 这些字符串可以包含多个修饰键和一个由 + 字符连接的单个键码。

[!NOTE] 加速器是不区分大小写的。

可用修饰键¶

• Command（或简写为 Cmd）
• Control（或简写为 Ctrl）
• CommandOrControl（或简写为 CmdOrCtrl）
• Alt
• Option
• AltGr
• Shift
• Super（或别名 Meta）

可用键码¶

• 0 到 9
• A 到 Z
• F1 到 F24
• 各种标点符号：), !, @, #, $, %, ^, &, *, (, :, ;, :, +, =, <, ,, _, -, >, ., ?, /, ~, `, {, ], [, |, \, }, "
• Plus
• Space
• Tab
• Capslock
• Numlock
• Scrolllock
• Backspace
• Delete
• Insert
• Return（或别名 Enter）
• Up、Down、Left 和 Right
• Home 和 End
• PageUp 和 PageDown
• Escape（或简写为 Esc）
• VolumeUp、VolumeDown 和 VolumeMute
• MediaNextTrack、MediaPreviousTrack、MediaStop 和 MediaPlayPause
• PrintScreen
• 数字小键盘按键
• num0 - num9
• numdec - 小数点键
• numadd - 小键盘 + 键
• numsub - 小键盘 - 键
• nummult - 小键盘 * 键
• numdiv - 小键盘 ÷ 键

跨平台修饰键¶

许多修饰键加速器在不同操作系统中映射到不同的按键。

[!IMPORTANT]

• 在 Linux 和 Windows 上，Command 修饰键没有任何效果。通常，你应该使用 CommandOrControl 修饰键，它在 macOS 上表示 ⌘ Cmd，在 Linux 和 Windows 上表示 Ctrl。
• 使用 Alt 而不是 Option。⌥ Opt 键仅存在于 macOS，而 Alt 会 在所有平台上映射到相应的修饰键。

示例¶

以下是一些用于常见编辑操作的跨平台 Electron 加速器示例：

• 复制：CommandOrControl+C
• 粘贴：CommandOrControl+V
• 撤销：CommandOrControl+Z
• 重做：CommandOrControl+Shift+Z

本地快捷键¶

本地键盘快捷键仅在应用获得焦点时触发。这些快捷键 映射到应用主 应用程序菜单 中的特定菜单项。

要定义本地键盘快捷键，你需要在创建 MenuItem 时配置 accelerator 属性。然后，使用该加速器时，与该菜单项关联的 click 事件将触发。

const { dialog, Menu, MenuItem } = require('electron/main')

const menu = new Menu()

// The first submenu needs to be the app menu on macOS
if (process.platform === 'darwin') {
  const appMenu = new MenuItem({ role: 'appMenu' })
  menu.append(appMenu)
}

// highlight-start
const submenu = Menu.buildFromTemplate([{
  label: 'Open a Dialog',
  click: () => dialog.showMessageBox({ message: 'Hello World!' }),
  accelerator: 'CommandOrControl+Alt+R'
}])
menu.append(new MenuItem({ label: 'Custom Menu', submenu }))
// highlight-end

Menu.setApplicationMenu(menu)

在上面的示例中，在 macOS 上按下 ⌘ Cmd+⌥ Opt+R， 或在其他平台上按下 Ctrl+Alt+R 时，将打开一个原生“你好，世界”对话框。

[!TIP] 即使菜单项被隐藏，加速器也可以工作。在 macOS 上，可以通过在构建 MenuItem 时 设置 acceleratorWorksWhenHidden: false 来禁用此功能。

[!TIP] 在 Windows 和 Linux 上，可以将 MenuItem 的 registerAccelerator 属性设置为 false， 使加速器在系统菜单中可见但不可用。

全局快捷键¶

全局键盘快捷键即使在应用失去焦点时也能工作。要配置全局键盘 快捷键，你可以使用 globalShortcut.register 函数来指定快捷键。

const { dialog, globalShortcut } = require('electron/main')

globalShortcut.register('CommandOrControl+Alt+R', () => {
  dialog.showMessageBox({ message: 'Hello World!' })
})

之后要注销快捷键，你可以使用 globalShortcut.unregisterAccelerator 函数。

const { globalShortcut } = require('electron/main')

globalShortcut.unregister('CommandOrControl+Alt+R')

[!WARNING] 在 macOS 上，globalShortcut 存在一个长期存在的 bug，导致它无法在 QWERTY 以外的键盘布局中正常工作（electron/electron#19747）。

窗口内的快捷键¶

在渲染进程中¶

如果你想在 BaseWindow 内处理键盘快捷键，你可以 在渲染进程中使用 addEventListener API 监听 keyup 和 keydown DOM 事件。

``fiddle docs/fiddles/features/keyboard-shortcuts/web-apis|focus=renderer.js function handleKeyPress (event) { // You can put code here to handle the keypress. document.getElementById('last-keypress').innerText = event.key console.log(You pressed ${event.key}`) }

window.addEventListener('keyup', handleKeyPress, true)

> [!NOTE]
> 第三个参数 `true` 表示该监听器将始终在其他监听器之前接收按键事件，因此无法对其调用 `stopPropagation()`。

#### 在主进程中拦截事件 {#intercepting-events-in-the-main-process}

[`before-input-event`](../api/web-contents.md#event-before-input-event) 事件
在渲染进程中分发 `keydown` 和 `keyup` 事件之前发出。它可以用于捕获并处理菜单中不可见的自定义快捷键。

```js title='Intercepting the Ctrl+I event from the main process'
const { app, BrowserWindow } = require('electron/main')

app.whenReady().then(() => {
  const win = new BrowserWindow()

  win.loadFile('index.html')
  win.webContents.on('before-input-event', (event, input) => {
    if (input.control && input.key.toLowerCase() === 'i') {
      console.log('Pressed Control+I')
      event.preventDefault()
    }
  })
})