Aller au contenu principal

globalShortcut

Détecte les événements de clavier lorsque l'application n'a pas le focus du clavier.

ProcessMain

Le module globalShortcut peut inscrire/désinscrire un raccourci clavier global avec le système d'exploitation afin que vous puissiez personnaliser les opérations pour les différents raccourcis.

[!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(() => {
// Enregistre un écouteur pour le raccourci 'CommandOrControl+X.
const ret = globalShortcut.register('CommandOrControl+X', () => {
console.log('CommandOrControl+X is pressed')
})

if (!ret) {
console.log('enregistrement échoué')
}

// Check si le raccourci est enregistré.
console.log(globalShortcut.isRegistered('CommandOrControl+X'))
})

app.on('will-quit', () => {
// Retire le raccourci.
globalShortcut.unregister('CommandOrControl+X')

// Supprime tous les raccourcis.
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).

Méthodes​

Le module globalShortcut dispose des méthodes suivantes :

globalShortcut.register(accelerator, callback)​

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

Retourne boolean - Si le raccourci a été enregistré avec succès.

Enregistre un raccourci global correspondant à accelerator. La callback est appelée lorsque le raccourci enregistré est saisi par l'utilisateur.

Lorsque l'accélérateur est déjà utilisé par d'autres applications, cet appel échouera silencieusement. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.

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 Piste Suivante"
  • "Media Piste Précédente"
  • "Media Stop"

globalShortcut.registerAll(accélérateurs, callback)​

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

Enregistre un raccourci global pour chaque élément accelerator de accelerators. La callback est appelée lorsque l'un des raccourcis enregistrés est saisi par l'utilisateur.

Lorsqu'un accélérateur donné est déjà pris par d'autres applications, cet appel échouera silencieusement. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.

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 Piste Suivante"
  • "Media Piste Précédente"
  • "Media Stop"

globalShortcut.isRegistered(accelerator)​

History
Version(s)Changes
None
API ADDED

Retourne un boolean - Si l'application à enregistrer l'accelerator.

Lorsque l'accelerator est déjà utilisé par d'autres applications, cet appel retournera toujours false. Ce comportement est prévu par les systèmes d'exploitation, car ils ne veulent pas que les applications se battent pour des raccourcis globaux.

globalShortcut.unregister(accelerator)​

History
Version(s)Changes
None
API ADDED

Supprime le raccourci global de l'accelerator.

globalShortcut.unregisterAll()​

History
Version(s)Changes
None
API ADDED

Supprime tous les raccourcis globaux.

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.