globalShortcut

当应用没有键盘焦点时检测键盘事件。

进程：主进程

🌐 Process: Main

globalShortcut 模块可以向操作系统注册/注销全局键盘快捷键，从而让你为各种快捷键自定义操作。

🌐 The globalShortcut module can register/unregister a global keyboard shortcut with the operating system so that you can customize the operations for various shortcuts.

note

快捷键是全局的；即使应用没有键盘焦点，它也能工作。这个模块在应用模块的 ready 事件触发之前无法使用。 另外请注意，也可以使用 Chromium 的 GlobalShortcutsPortal 实现，这允许应用在 Wayland 会话中运行时绑定全局快捷键。

const { app, globalShortcut } = require('electron')

// Enable usage of Portal's globalShortcuts. This is essential for cases when
// the app runs in a Wayland session.
app.commandLine.appendSwitch('enable-features', 'GlobalShortcutsPortal')

app.whenReady().then(() => {
  // Register a 'CommandOrControl+X' shortcut listener.
  const ret = globalShortcut.register('CommandOrControl+X', () => {
    console.log('CommandOrControl+X is pressed')
  })

  if (!ret) {
    console.log('registration failed')
  }

  // Check whether a shortcut is registered.
  console.log(globalShortcut.isRegistered('CommandOrControl+X'))
})

app.on('will-quit', () => {
  // Unregister a shortcut.
  globalShortcut.unregister('CommandOrControl+X')

  // Unregister all shortcuts.
  globalShortcut.unregisterAll()
})

tip

另请参见：键盘快捷键详细指南。

方法

🌐 Methods

globalShortcut 模块具有以下方法：

🌐 The globalShortcut module has the following methods:

globalShortcut.register(accelerator, callback)

• accelerator 字符串 - 一个 加速器 快捷方式。
• callback 函数

返回 boolean - 快捷方式是否注册成功。

🌐 Returns boolean - Whether or not the shortcut was registered successfully.

注册一个全局快捷键 accelerator。当用户按下已注册的快捷键时，将调用 callback。

🌐 Registers a global shortcut of accelerator. The callback is called when the registered shortcut is pressed by the user.

当加速键已被其他应用使用时，此调用将默默失败。这种行为是操作系统故意设计的，因为它们不希望应用争夺全局快捷键。

🌐 When the accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.

以下快捷键在 macOS 10.14 Mojave 上将无法成功注册，除非应用已被授权为受信任的辅助功能客户端：

🌐 The following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:

• 媒体播放/暂停
• 媒体下一曲
• 媒体 上一曲
• 媒体停止

globalShortcut.registerAll(accelerators, callback)

• accelerators string[] - 一个 accelerator 快捷方式数组。
• callback 函数

在 accelerators 中为所有 accelerator 项注册全局快捷键。当用户按下任何已注册的快捷键时，将调用 callback。

🌐 Registers a global shortcut of all accelerator items in accelerators. The callback is called when any of the registered shortcuts are pressed by the user.

当某个加速键已被其他应用占用时，此调用将会悄无声息地失败。这种行为是操作系统有意为之的，因为它们不希望应用争抢全局快捷键。

🌐 When a given accelerator is already taken by other applications, this call will silently fail. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.

以下快捷键在 macOS 10.14 Mojave 上将无法成功注册，除非应用已被授权为受信任的辅助功能客户端：

🌐 The following accelerators will not be registered successfully on macOS 10.14 Mojave unless the app has been authorized as a trusted accessibility client:

• 媒体播放/暂停
• 媒体下一曲
• 媒体 上一曲
• 媒体停止

globalShortcut.isRegistered(accelerator)

• accelerator 字符串 - 一个 加速器 快捷方式。

返回 boolean - 表示该应用是否已注册 accelerator。

🌐 Returns boolean - Whether this application has registered accelerator.

当加速键已被其他应用占用时，此调用仍将返回 false。操作系统的这种行为是有意为之，因为它们不希望应用争夺全局快捷键。

🌐 When the accelerator is already taken by other applications, this call will still return false. This behavior is intended by operating systems, since they don't want applications to fight for global shortcuts.

globalShortcut.unregister(accelerator)

• accelerator 字符串 - 一个 加速器 快捷方式。

取消注册 accelerator 的全局快捷键。

🌐 Unregisters the global shortcut of accelerator.

globalShortcut.unregisterAll()

取消注册所有全局快捷方式。

🌐 Unregisters all of the global shortcuts.