跳转到主要内容

键盘快捷键

加速键​

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

注意

加速键不区分大小写。

可用的修饰符​

  • Command (或简写 Cmd)
  • Control (或简写 Ctrl)
  • CommandOrControl (或简写 CmdOrCtrl)
  • Alt
  • Option
  • AltGr
  • Shift
  • Super (或别名 Meta)

可用的键码​

  • 0 到 9
  • A 到 Z
  • F1 到 F24
  • 各种标点符号：), !, @, #, $, %, ^, &, *, (, :, ;, :, +, =, <, ,, _, -, >, ., ?, /, ~, `, {, ], [, |, \, }, "
  • 加号
  • 空格
  • 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 存在一个长期存在的错误，导致它无法与 QWERTY 以外的键盘布局一起工作 (electron/electron#19747)。

窗口内的快捷键​

在渲染进程中​

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

docs/fiddles/features/keyboard-shortcuts/web-apis (40.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()
    }
  })
})