メインコンテンツへ飛ぶ

globalShortcut

アプリケーションにキーボードフォーカスがないときにキーボードイベントを検出します。

プロセス: メイン

globalShortcut モジュールは、オペレーティングシステムに対してグローバルショートカットを登録/登録解除することができます。そのため、様々なショートカットに対する操作をカスタマイズすることができます。

[!NOTE] ショートカットはグローバルです。そのため、アプリにキーボードフォーカスがない場合でも機能します。 app モジュールの ready イベントが発生するまでは、このモジュールは使用できません。 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] こちらもご参照ください: キーボードショートカットに関する詳細ガイド。

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

戻り値 boolean - ショートカットが正常に登録されたかどうか.

accelerator のグローバルショートカットを登録します。 callback は登録したショートカットがユーザに押下されたときに呼び出されます。

アクセラレータが他のアプリケーションによってすでに使用されている場合、この呼び出しは何も通知することなく失敗します。この動作は、アプリケーションにグローバルショートカットの取り合いをさせたくないため、オペレーティングシステムによって意図されたものです。

以下のアクセラレータは、アプリが 信頼できるアクセシビリティクライアント として認識されていない限り macOS 10.14 Mojave に正常に登録されません。

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

globalShortcut.registerAll(accelerators, callback)​

History
Version(s)Changes
None
API ADDED

accelerators 内の全ての accelerator のグローバルショートカットを登録します。 callback は登録したいずれかのショートカットがユーザに押下されたときに呼び出されます。

与えられたアクセラレータが他のアプリケーションによってすでに使用されている場合、この呼び出しは何も通知することなく失敗します。この動作は、アプリケーションにグローバルショートカットの取り合いをさせたくないため、オペレーティングシステムによって意図されたものです。

以下のアクセラレータは、アプリが 信頼できるアクセシビリティクライアント として認識されていない限り macOS 10.14 Mojave に正常に登録されません。

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

globalShortcut.isRegistered(accelerator)​

History
Version(s)Changes
None
API ADDED

戻り値 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.