commands

Der Schlüssel commands ist ein Objekt, und jede Tastenkombination ist eine Eigenschaft davon. Der Name der Eigenschaft ist der Name der Tastenkombination.

Der Wert jeder Tastenkombination ist ein Objekt mit bis zu 2 Eigenschaften:

1. suggested_key Optional: die Tastenkombination, die die Tastenkombination aktiviert.
2. description Optional: ein String, der die Tastenkombination beschreibt, d. h. was sie macht.

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

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

Der Wert jeder Eigenschaft ist die Tastenkombination für den Befehl auf dieser Plattform, angegeben als 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 auf keiner Plattform, die nicht ausgeschlossen wurde, eine Tastenkombination, es sei denn, sie wird vom Benutzer oder durch die commands.update API konfiguriert.

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 folgende Tastenkombinationen:

1. "toggle-feature": erreichbar mit Ctrl + Shift + U auf Linux und Alt + Shift + U auf allen anderen Plattformen.
2. "do-another-thing": erreichbar mit Ctrl + Shift + Y auf allen Plattformen.
3. "do-something-else": erreichbar mit Ctrl + Shift + P nur auf Linux und ohne Standard-Tastenkombination auf anderen Plattformen.
4. "do-nothing-yet": setzt keine Tastenkombination, erlaubt jedoch dem Benutzer oder der commands.update API, eine Tastenkombination festzulegen.

Sie können auf diese Befehle mithilfe eines Codes wie diesem reagieren, hier für den Befehl "toggle-feature":

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

Es gibt 4 spezielle Tastenkombinationen mit Standardaktionen, bei denen das commands.onCommand-Ereignis nicht ausgelöst wird:

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

Die Verfügbarkeit dieser speziellen Tastenkombinationen variiert je nach Manifest-Version und Browser, wie folgt:

Beispiel: Dieses JSON definiert eine Tastenkombination, die die Schaltfläche der Browser-Aktion der Erweiterung anklickt:

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

Es gibt zwei gültige Formate für Tastenkombinationen: als Tastenkombination oder als Medientaste.

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

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

2. Sekundäre Modifikationstaste (optional). Falls angegeben, muss diese entweder "Shift" sein oder (für Firefox ≥ 63) eine der folgenden: "Ctrl", "Alt", "Command" oder "MacCtrl". Sie darf nicht dieselbe Modifikationstaste sein wie die Hauptmodifikationstaste.

3. Schlüssel (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 über Erweiterungskürzel verwalten zuweisen. Ihre Erweiterung kann diese Tasten nicht über die Manifestdatei zuweisen, jedoch mit commands.update.

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

Der Schlüssel wird dann als String angegeben, der die Reihe der Tastenwerte enthält, in der oben beschriebenen Reihenfolge, getrennt durch "+", z. B. "Ctrl+Shift+Z".

Wenn eine Tastenkombination bereits vom Browser (z. B. "Ctrl+P") oder von einer bestehenden Erweiterung verwendet wird, können Sie sie nicht überschreiben. Sie können sie definieren, jedoch wird Ihr Ereignishandler nicht aufgerufen, wenn der Benutzer die Tastenkombination drückt.

Alternativ kann die Kombination als eine der folgenden Medientasten angegeben werden:

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

Tastenkombinationen können mit commands.update() aktualisiert werden. Benutzer können Tastenkombinationen auch über die Option "Erweiterungskürzel verwalten" in about:addons in Firefox aktualisieren, wie in diesem Video dargestellt. In Chrome können Benutzer Tastenkombinationen unter chrome://extensions/shortcuts ändern.

Definieren Sie eine einzige Tastenkombination, nur mit der Standard-Tastenkombination:

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

Definieren Sie zwei Tastenkombinationen, eine mit einer plattformabhängigen 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"
    }
  }
}