跳转到主要内容

键盘快捷键

快捷键组合​

快捷键组合（Accelerators）是可以在整个 Electron 中用来表示键盘快捷键的字符串。这些字符串可以包含多个修饰键和一个由 + 字符连接的单个按键代码。

注意

快捷键组合是不区分大小写的。

可用修饰键​

  • 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 - 小键盘 ÷ 键

跨平台修饰键​

许多修饰键组合在不同操作系统上会映射到不同的按键。

修饰键macOSWindows 和 Linux
CommandOrControlCommand (⌘)Control
CommandCommand (⌘)N/A
ControlControl (^)Control
AltOption (⌥)Alt
OptionOption (⌥)N/A
Super (Meta)Command (⌘)Windows (⊞)
信息
  • 在 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)
}

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

Menu.setApplicationMenu(menu)

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

提示

即使菜单项被隐藏，快捷键组合仍然可以工作。在 macOS 上，可以通过在构建 MenuItem 时设置 acceleratorWorksWhenHidden: false 来禁用此功能。

提示

在 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')
警告

在 macOS 上，globalShortcut 存在一个长期存在的 bug，它会导致它在 QWERTY 以外的键盘布局下无法工作（electron/electron#19747）。

窗口内的快捷键​

在渲染器进程中​

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

docs/fiddles/features/keyboard-shortcuts/web-apis (39.0.0)在 Fiddle 中打开
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)
注意

第三个参数 true 表示侦听器将始终在其他侦听器之前接收按键事件，因此无法调用 stopPropagation()。

在主进程中拦截事件​

在将 keydown 和 keyup 事件分发到渲染器进程之前，会发出 before-input-event 事件。它可以用于捕获和处理菜单中不可见的自定义快捷键。

从主进程拦截 Ctrl+I 事件
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()
    }
  })
})