globalShortcut registriert Tastenkürzel system-weit — sie greifen auch, wenn die App nicht im Fokus ist. Klassische Use-Cases: Screenshot-Tools, Quick-Capture-Apps, Toggle-Hotkey für Tray-Apps. Hier wie's geht und was die typischen Stolperfallen sind.
Registrieren und auflösen
import { app, globalShortcut } from 'electron';
app.whenReady().then(() => {
const ok = globalShortcut.register('CmdOrCtrl+Shift+Space', () => {
console.log('Hotkey gedrückt');
mainWindow.show();
mainWindow.focus();
});
if (!ok) {
console.warn('Konnte Hotkey nicht registrieren — vergeben?');
}
});
// Beim Quit aufräumen
app.on('will-quit', () => {
globalShortcut.unregisterAll();
});register gibt true zurück bei Erfolg, false wenn der Hotkey schon vergeben ist (z. B. von einer anderen App).
Mehrere Shortcuts
const shortcuts = {
'CmdOrCtrl+Shift+Space': () => toggleMainWindow(),
'CmdOrCtrl+Shift+N': () => createQuickNote(),
'CmdOrCtrl+Shift+C': () => captureScreen()
};
for (const [accel, handler] of Object.entries(shortcuts)) {
globalShortcut.register(accel, handler);
}Belegung prüfen
if (globalShortcut.isRegistered('CmdOrCtrl+Shift+Space')) {
console.log('Bereits von dieser App registriert');
}
// Einzelnen freigeben
globalShortcut.unregister('CmdOrCtrl+Shift+Space');
// Alle freigeben
globalShortcut.unregisterAll();isRegistered prüft nur eigene Registrierungen — nicht, ob eine andere App das Kürzel hält.
Konflikt-Strategie
System-weite Shortcuts sind ein knappes Gut — User hat schon Spotlight, Window-Manager-Hotkeys, andere Apps. Pragmatisch:
- User-konfigurierbar: Hotkey in Settings einstellbar machen
- Sinnvolle Defaults: ungewöhnliche Kombis (
Cmd+Shift+Alt+...) statt Standard-Tasten - Bei Konflikt warnen: User informieren, wenn Registrierung fehlschlägt
let currentShortcut = store.get('hotkey', 'CmdOrCtrl+Shift+Space');
function updateShortcut(newShortcut) {
globalShortcut.unregister(currentShortcut);
const ok = globalShortcut.register(newShortcut, handleHotkey);
if (ok) {
currentShortcut = newShortcut;
store.set('hotkey', newShortcut);
return true;
} else {
// Re-register old
globalShortcut.register(currentShortcut, handleHotkey);
return false;
}
}Plattform-Eigenheiten
| Plattform | Hinweise |
|---|---|
| macOS | Accessibility-Permission ggf. nötig; manche Kombis vom System reserviert |
| Windows | Wenig Restriktion, aber Konflikte mit anderen Apps häufig |
| Linux | Hängt stark vom Window-Manager ab; manche WMs intercepten zuerst |
Auf macOS ist Accessibility-Permission seit länger nötig für manche Hotkey-Patterns — beim ersten Mal wird der User vom System gefragt.
Kein globalShortcut für In-App-Hotkeys
Wichtige Unterscheidung: globalShortcut ist für system-weite Hotkeys gedacht. Für „funktioniert nur, wenn meine App den Fokus hat":
- Menu-Accelerators (im
Menu-Template) — siehe Menu-Artikel - Renderer-Listener —
keydown-Events im Renderer-DOM before-input-eventimwebContentsfür Renderer-globale Hotkeys
globalShortcut ist „greedy" und blockiert die Tasten für alle anderen Apps — das willst du nur, wenn das System-weit sein soll.
Besonderheiten
unregisterAll() beim Quit ist Pflicht.
Ohne Cleanup bleiben Hotkeys auf dem System gebunden, bis das OS die Bindung „vergisst" — auf manchen Plattformen erst beim Reboot. App-Quit-Handler ist der Default-Cleanup-Punkt.
register kann fehlschlagen — Rückgabewert prüfen.
Wenn der Hotkey schon vergeben ist (von macOS Spotlight, einer anderen App): register gibt false zurück. Stille Fehler sind verwirrend für User — bei Misserfolg eine Notification oder Dialog zeigen.
globalShortcut nur für SYSTEM-weite Hotkeys.
Für In-App-Hotkeys: Menü-Accelerators (sichtbar im UI als Hint) oder Renderer-Eventlistener. globalShortcut blockiert die Taste für ALLE anderen Apps — bei „nur wenn meine App fokussiert" der falsche Mechanismus.
macOS Accessibility-Permission kann nötig sein.
Manche Hotkey-Patterns (z. B. mit Funktionstasten) werden auf macOS erst nach Accessibility-Genehmigung registriert. Beim ersten Mal Dialog vom System; User muss in den Systemeinstellungen die App freischalten.
Hotkey-Ergonomie: 3-Modifier-Kombis sind safer.
Cmd+Shift+Alt+X ist meist frei. Cmd+S ist von jedem Editor belegt. Für system-weite Shortcuts lieber 3-Modifier-Kombi default, mit User-Customization-Option.
isRegistered sieht nur eigene Registrierungen.
Es gibt KEINE API, um zu prüfen ob ein Hotkey systemweit vergeben ist. Nur eigene erkennt isRegistered. Bei Konflikt: einfach register versuchen und Rückgabewert prüfen.