跳转到主内容

globalShortcut

在应用程序没有键盘焦点时，监听键盘事件。

ProcessMain

globalShortcut 模块可以在操作系统中注册/注销全局快捷键, 以便可以为操作定制各种快捷键。

[!NOTE] The shortcut is global; it will work even if the app does not have the keyboard focus. This module cannot be used before the ready event of the app module is emitted. On Linux Wayland sessions, shortcuts are bound through the desktop portal — see Usage on Linux below.

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

app.whenReady().then(() => {
  // 注册一个'CommandOrControl+X' 快捷键监听器
  const ret = globalShortcut.register('CommandOrControl+X', () => {
    console.log('CommandOrControl+X is pressed')
  })

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

  // 检查快捷键是否注册成功
  console.log(globalShortcut.isRegistered('CommandOrControl+X'))
})

app.on('will-quit', () => {
  // 注销快捷键
  globalShortcut.unregister('CommandOrControl+X')

  // 注销所有快捷键
  globalShortcut.unregisterAll()
})

[!TIP] See also: A detailed guide on Keyboard Shortcuts.

Usage on Linux​

On X11, shortcuts are grabbed directly from the X server and work like on other platforms.

On Wayland, compositors do not let apps grab keys directly. Electron instead uses the org.freedesktop.portal.GlobalShortcuts portal, which changes the module's behavior in several ways:

  • Your app must have a valid portal identity. Set desktopName in package.json (or call app.setDesktopName()) to a reverse-DNS ID matching your installed .desktop file, e.g. com.example.MyApp.desktop. With an invalid or unresolvable ID, GNOME 50.0/50.1 denies every bind — silently, from the app's perspective.
  • GNOME shows a consent dialog the first time an app binds shortcuts, pre-filled with the accelerators the app requested. KDE Plasma binds silently without a dialog (shortcuts are visible and editable in System Settings).
  • Bindings persist across relaunches, keyed by the app's portal identity: after the user accepts once, registering the same shortcuts on later launches re-binds them silently.
  • The portal path is enabled by default. The GlobalShortcutsPortal and GlobalShortcutsPortalPreferredTrigger features are on by default, so no feature flags are needed — including on GNOME (see #52221).

方法​

globalShortcut 模块具有以下方法:

globalShortcut.register(accelerator, callback)​

History
Version(s)Changes
None
API ADDED
  • accelerator string - An accelerator shortcut.
  • callback Function

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

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

如果指定的快捷键已经被其他应用程序注册掉, 调用会默默失败。该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。

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

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

globalShortcut.registerAll(accelerators, callback)​

History
Version(s)Changes
None
API ADDED
  • accelerators string[] - An array of accelerator shortcuts.
  • callback Function

注册多个全局快捷键。当用户按下注册快捷键时， callback 会被调用。

如果定义的快捷键已经被其他应用占用，这个调用会失效。该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。

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

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

globalShortcut.isRegistered(accelerator)​

History
Version(s)Changes
None
API ADDED

Returns boolean - 表示 accelerator 全局快捷键是否注册成功

当快捷键已经被其他应用程序注册时, 此调用将返回 false。该特性由操作系统定义，因为操作系统不希望多个程序的全局快捷键互相冲突。

globalShortcut.unregister(accelerator)​

History
Version(s)Changes
None
API ADDED

注销 accelerator 的全局快捷键。

globalShortcut.unregisterAll()​

History
Version(s)Changes
None
API ADDED

注销所有的全局快捷键（清空该应用程序的全局快捷键）。

globalShortcut.setSuspended(suspended)​

History
Version(s)Changes
None
API ADDED
  • suspended boolean - Whether global shortcut handling should be suspended.

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

Returns boolean - Whether global shortcut handling is currently suspended.