Keybindings

Tastenkürzel verbinden eine Tastenkombination mit einem Command. Der Benutzer drückt die Tasten, der Host löst den zugehörigen Command aus. Wie bei Menüs und Toolbar-Buttons kann ein when-Ausdruck die Gültigkeit auf bestimmte Kontexte einschränken.

Zurück zur Contributions-Übersicht oder zur Hauptübersicht.

Manifest-Deklaration

"contributes": {
  "keybindings": [
    {
      "command": "assets.list",
      "key": "Ctrl+Shift+A",
      "mac": "Cmd+Shift+A",
      "when": ""
    },
    {
      "command": "assets.save",
      "key": "Ctrl+S",
      "when": "activeDocument == assets.editor && isDirty"
    }
  ]
}

Feld	Pflicht	Beschreibung
`command`	ja	Referenz auf den auszuführenden Command.
`key`	ja	Tastenkombination für Windows und Linux (z.B. `Ctrl+Shift+A`).
`mac`	nein	Alternative Kombination für macOS. Wenn das Feld fehlt, wird `key` auch auf macOS verwendet.
`when`	nein	Kontextausdruck für bedingte Gültigkeit. Das Tastenkürzel wird nur ausgewertet, wenn der Ausdruck wahr ist.

Tastenkombinationen

Tastenkombinationen werden als String angegeben. Die Notation folgt einem einfachen Schema:

Modifier	Windows/Linux	macOS
Steuerung	`Ctrl`	`Cmd`
Umschalt	`Shift`	`Shift`
Alt	`Alt`	`Alt`

Modifier werden mit + verkettet, gefolgt von der Taste:

Ctrl+S — Steuerung + S
Ctrl+Shift+P — Steuerung + Umschalt + P
Alt+F4 — Alt + F4
F5 — Funktionstaste ohne Modifier

Der Host wandelt den String intern in einen TShortCut-Wert um. Ungültige Kombinationen werden beim Laden gemeldet und ignoriert.

Kontextbezogene Kürzel

Der when-Ausdruck ermöglicht es, dass dasselbe Tastenkürzel in verschiedenen Kontexten verschiedene Commands auslöst:

"keybindings": [
  {
    "command": "assets.save",
    "key": "Ctrl+S",
    "when": "activeDocument == assets.editor"
  },
  {
    "command": "reports.save",
    "key": "Ctrl+S",
    "when": "activeDocument == reports.editor"
  }
]

In diesem Beispiel löst Ctrl+S den Speichern-Command des jeweils aktiven Editors aus. Wenn der Asset-Editor aktiv ist, wird assets.save ausgeführt; wenn der Berichts-Editor aktiv ist, wird reports.save ausgeführt. Ohne when-Ausdruck würde der Host bei Konflikten den zuletzt registrierten Command verwenden.

Konflikterkennung

Wenn zwei Add-ins dasselbe Tastenkürzel ohne when-Ausdruck registrieren, entsteht ein Konflikt. Der Host löst Konflikte nach dem First-Registered-Wins-Prinzip: Das zuerst registrierte Kürzel gewinnt, das zweite wird ignoriert und im Log protokolliert. Um Konflikte zu vermeiden, sollten Add-ins möglichst spezifische when-Ausdrücke verwenden oder ungewöhnliche Tastenkombinationen wählen.

Programmatische Registrierung

Wie bei allen Contribution-Typen ist die deklarative Registrierung im Manifest der bevorzugte Weg. Für dynamische Szenarien steht IKeybindingService bereit:

AContext.Subscribe(
  FHost.Keybindings.RegisterKeybinding('Ctrl+Shift+R',
    'assets.refresh', 'activeDocument == assets.editor')
);

Weiter zum Skin-Vertrag oder zurück zur Contributions-Übersicht.

Inhaltsverzeichnis