globalShortcut

Detecta eventos de teclado quando o aplicativo não tiver o foco do teclado.

Process: Main

O módulo globalShortcut pode registrar/cancelar o registro de um atalho de teclado global com o sistema operativo que você possa personalizar as operações para os vários atalhos.

[!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. Please also note that it is also possible to use Chromium's GlobalShortcutsPortal implementation, which allows apps to bind global shortcuts when running within a Wayland session.

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] See also: A detailed guide on Keyboard Shortcuts.

Métodos

O módulo globalShortcut tem os seguintes métodos:

globalShortcut.register(accelerator, callback)

• accelerator string - An accelerator shortcut.
• callback Function

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

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

Quando o acelerador já está sendo utilizado por outras aplicações, esta chamada falhará silenciosamente. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.

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)

• accelerators string[] - An array of accelerator shortcuts.
• callback Function

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. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.

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)

• accelerator string - An accelerator shortcut.

Retorna boolean - Se esta aplicação registrou o accelerator.

Quando o acelerador já está sendo utilizado por outras aplicações, esta ainda retorna false. Este comportamento é pretendido pelos sistemas operacionais, uma vez que eles não querem que os aplicativos lutem por atalhos globais.

globalShortcut.unregister(accelerator)

• accelerator string - An accelerator shortcut.

Não registra o atalho global de accelerator.

globalShortcut.unregisterAll()

Não registra todos os atalhos globais.