globalShortcut¶

在应用程序没有键盘焦点时检测键盘事件。

进程：主进程

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

[!NOTE] 该快捷键是全局的；即使应用没有键盘焦点，它也会生效。在 app 模块的 ready 事件发出之前，不能使用此模块。 在 Linux Wayland 会话中，快捷键通过桌面门户绑定—— 参见下文中的 在 Linux 上使用。

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

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] 另请参阅：键盘快捷键详细指南。

在 Linux 上使用¶

在 X11 上，快捷键直接从 X 服务器抓取，行为与其他平台类似。

在 Wayland 上，合成器不允许应用直接抓取按键。Electron 转而使用 org.freedesktop.portal.GlobalShortcuts 门户，这会在几个方面改变该模块的行为：

• 你的应用必须具有有效的门户身份。 在 package.json 中设置 desktopName（或调用 app.setDesktopName()），将其设置为与已安装的 .desktop 文件匹配的反向 DNS ID，例如 com.example.MyApp.desktop。如果 ID 无效或无法解析，GNOME 50.0/50.1 会拒绝所有绑定——从应用的角度来看，这是静默的。
• GNOME 会显示同意对话框 当应用首次绑定快捷键时，其中已预填应用请求的加速器。KDE Plasma 会静默绑定，不显示对话框（快捷键可在系统设置中查看和编辑）。
• 绑定在重新启动后持久保留，以应用的门户身份为键：用户接受一次后， 在后续启动时注册相同快捷键会静默地重新绑定它们。
• 门户路径默认启用。 GlobalShortcutsPortal 和 GlobalShortcutsPortalPreferredTrigger 功能默认开启，因此无需功能标志—— 包括在 GNOME 上（参见 #52221）。

事件¶

globalShortcut 模块会发出以下事件：

事件：'registration-resolved' Linux¶

• accelerator string - 一个加速器快捷键。
• callback Function

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

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

当该加速器已被其他应用程序占用时，此调用会静默失败。这是操作系统的预期行为，因为它们不希望应用程序争夺全局快捷键。

在 Linux Wayland 上，返回值仅表示绑定请求已提交给桌面门户；门户会异步解析它，实际结果由 registration-resolved 事件报告。

除非应用已被授权为受信任的辅助功能客户端，否则以下加速器在 macOS 10.14 Mojave 上不会注册成功：

• "Media Play/Pause"
• "Media Next Track"
• "Media Previous Track"
• "Media Stop"

globalShortcut.registerAll(accelerators, callback)¶

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

返回 boolean - 此应用程序是否已注册 accelerator。

当该加速器已被其他应用程序占用时，此调用仍会返回 false。这是操作系统的预期行为，因为它们不希望应用程序争夺全局快捷键。

globalShortcut.unregister(accelerator)¶

注销所有全局快捷键。

globalShortcut.setSuspended(suspended)¶

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