commands

Der commands-Schlüssel ist ein Objekt, und jeder Shortcut ist eine Eigenschaft davon. Der Name der Eigenschaft ist der Name des Shortcuts.

Der Wert jedes Shortcuts ist ein Objekt mit bis zu 2 Eigenschaften:

1. suggested_key Optional: die Tastenkombination, die den Shortcut aktiviert.
2. description Optional: ein String, der den Shortcut beschreibt, d.h. was er tut.

Die Eigenschaft suggested_key ist ein Objekt mit beliebigen oder keinen dieser Eigenschaften (alle Strings):

• "default"
• "mac"
• "linux"
• "windows"
• "chromeos"
• "android"
• "ios"

Der Wert jeder Eigenschaft ist der Tastatur-Shortcut für den Befehl auf dieser Plattform, als ein String mit durch "+" getrennten Tasten. Der Wert für "default" wird auf allen Plattformen verwendet, die nicht explizit aufgeführt sind. Wenn "default" nicht enthalten ist, hat der Befehl keinen Tastatur-Shortcut auf Plattformen, die nicht enthalten sind, es sei denn, ein Shortcut wird vom Benutzer oder durch die commands.update-API konfiguriert.

Zum Beispiel:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event to the extension"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  },
  "do-something-else": {
    "suggested_key": {
      "linux": "Ctrl+Shift+P"
    }
  },
  "do-nothing-yet": {}
}

Dieses JSON definiert diese Shortcuts:

1. "toggle-feature", zugänglich mit Ctrl + Shift + U auf Linux und Alt + Shift + U auf allen anderen Plattformen.
2. "do-another-thing", zugänglich mit Ctrl + Shift + Y auf allen Plattformen.
3. "do-something-else", zugänglich mit Ctrl + Shift + P nur auf Linux, und kein Standard-Shortcut auf anderen Plattformen.
4. "do-nothing-yet", setzt keinen Tastatur-Shortcut, ermöglicht aber einen Shortcut vom Benutzer oder mit der commands.update-API zu setzen.

Sie können für die Befehle mit Code wie diesem lauschen, in diesem Fall für den "toggle-feature"-Befehl:

browser.commands.onCommand.addListener((command) => {
  if (command === "toggle-feature") {
    console.log("Toggling the feature!");
  }
});

Es gibt 4 spezielle Shortcuts mit Standardaktionen, für die das Ereignis commands.onCommand nicht ausgelöst wird:

• _execute_browser_action: wirkt wie ein Klick auf eine Toolbar-Schaltfläche, die mit browserAction erstellt oder im Schlüssel browser_action in der manifest.json-Datei angegeben wird.
• _execute_action: wirkt wie ein Klick auf eine Toolbar-Schaltfläche, die mit action erstellt oder im Schlüssel action in der manifest.json-Datei angegeben wird.
• _execute_page_action: wirkt wie ein Klick auf eine Adressleisten-Schaltfläche, die mit pageAction erstellt oder im Schlüssel page_action in der manifest.json-Datei angegeben wird.
• _execute_sidebar_action: öffnet die Sidebar der Erweiterung, die im Schlüssel sidebar_action der manifest.json-Datei angegeben ist.

Die Verfügbarkeit dieser speziellen Shortcuts variiert zwischen Manifest-Versionen und Browsern, wie folgt:

Zum Beispiel definiert dieses JSON eine Tastenkombination, die die Browser-Aktion der Erweiterung klickt:

"commands": {
  "_execute_browser_action": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}

Es gibt zwei gültige Formate für Shortcut-Tasten: als Tastenkombination oder als Medientaste.

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

1. Modifier (obligatorisch, außer bei Funktionstasten). Dies kann einer der folgenden sein: "Ctrl", "Alt", "Command" oder "MacCtrl".

2. Zweit-Modifier (optional). Wenn angegeben, muss dies entweder "Shift" oder (für Firefox ≥ 63) einer von "Ctrl", "Alt", "Command" oder "MacCtrl" sein. Darf nicht der bereits als Hauptmodifier verwendete Modifier sein.

3. Taste (obligatorisch). Dies kann eine der folgenden sein:

   • die Buchstaben A – Z
   • die Zahlen 0 – 9
   • die Funktionstasten F1 – F12

     Hinweis: Ab Firefox 135 können Benutzer die Tasten F13 bis F19 einer Erweiterung zuweisen, indem sie Erweiterungs-Shortcuts verwalten verwenden. Ihre Erweiterung kann diese Tasten nicht aus der Manifest-Datei zuweisen. Sie kann sie jedoch mit commands.update zuweisen.

   • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

Die Taste wird dann als ein String angegeben, der die Menge der Tastenwerte in der oben aufgeführten Reihenfolge enthält, getrennt durch "+". Zum Beispiel, "Ctrl+Shift+Z".

Wenn eine Tastenkombination bereits vom Browser (wie "Ctrl+P") oder durch ein vorhandenes Add-on verwendet wird, können Sie diese nicht überschreiben. Sie können sie definieren, aber Ihr Ereignishandler wird nicht aufgerufen, wenn der Benutzer die Tastenkombination drückt.

Alternativ kann der Shortcut als eine dieser Medientasten angegeben werden:

• "MediaNextTrack"
• "MediaPlayPause"
• "MediaPrevTrack"
• "MediaStop"

In Firefox kann Ihre Erweiterung die Einstellung der Shortcut-Tasten mithilfe von commands.update() aktualisieren. Benutzer können Shortcuts mit der Option Erweiterungs-Shortcuts verwalten unter about:addons aktualisieren, wie in diesem Video gezeigt. Ihre Erweiterung kann diese Option mit commands.openShortcutSettings() öffnen.

In Chrome können Erweiterungen Shortcut-Tasten nicht programmatisch aktualisieren. Benutzer können Shortcuts unter chrome://extensions/shortcuts ändern, das mit tabs.create() geöffnet werden kann.

Safari unterstützt keine programmatische oder benutzergesteuerte Änderung von Shortcuts für Erweiterungen.

Definieren Sie einen Tastatur-Shortcut, der nur die Standard-Tastenkombination verwendet:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

Definieren Sie zwei Tastatur-Shortcuts, einen mit einer plattformenspezifischen Tastenkombination:

"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Alt+Shift+U",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  },
  "do-another-thing": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y"
    }
  }
}