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)

History

Version(s)	Changes
None	API ADDED

• accelerator string - 一个加速器快捷方式。
• 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)

History

Version(s)	Changes
None	API ADDED

• accelerators string[] - 一组加速器快捷键。
• 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)

History

Version(s)	Changes
None	API ADDED

• accelerator string - 一个加速器快捷方式。

返回 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)

History

Version(s)	Changes
None	API ADDED

• accelerator string - 一个加速器快捷方式。

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

🌐 Unregisters the global shortcut of accelerator.

globalShortcut.unregisterAll()

History

Version(s)	Changes
None	API ADDED

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

🌐 Unregisters all of the global shortcuts.

globalShortcut.setSuspended(suspended)

History

Version(s)	Changes
None	API ADDED

• suspended boolean - 是否应该暂停全局快捷键的处理。

暂停或恢复全局快捷键处理。暂停时，所有已注册的全局快捷键将停止监听按键。当恢复时，所有先前注册的快捷键将重新开始监听。在处理被暂停期间，新快捷键注册将失败。

🌐 Suspends or resumes global shortcut handling. When suspended, all registered global shortcuts will stop listening for key presses. When resumed, all previously registered shortcuts will begin listening again. New shortcut registrations will fail while handling is suspended.

当你希望临时允许用户按键组合而不被你的应用拦截时，这可能会很有用，例如在显示用于重新绑定快捷键的用户界面时。

🌐 This can be useful when you want to temporarily allow the user to press key combinations without your application intercepting them, for example while displaying a UI to rebind shortcuts.

globalShortcut.isSuspended()

History

Version(s)	Changes
None	API ADDED

返回 boolean - 当前全局快捷键处理是否已被暂停。

🌐 Returns boolean - Whether global shortcut handling is currently suspended.