commands

Typ Object
Verpflichtend Nein
Manifest-Version 2 oder höher
Beispiel
json
"commands": {
  "toggle-feature": {
    "suggested_key": {
      "default": "Ctrl+Shift+Y",
      "linux": "Ctrl+Shift+U"
    },
    "description": "Send a 'toggle-feature' event"
  }
}

Nutzen Sie den Schlüssel commands, um eine oder mehrere Tastenkombinationen für Ihre Erweiterung zu definieren.

Jede Tastenkombination wird durch einen Namen, eine Tastenkombination und eine Beschreibung definiert. Nachdem Sie in der Datei manifest.json Ihrer Erweiterung Befehle definiert haben, können Sie auf die entsprechenden Tastenkombinationen mit der commands API reagieren.

Syntax

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:

json
"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":

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

Spezielle Tastenkombinationen

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

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

Manifest V2 Manifest V3
_execute_browser_action Ja Nein
_execute_action Nein Ja
_execute_page_action Ja Nur Firefox
_execute_sidebar_action Nur Firefox Nur Firefox

Hinweis: Wenn der Benutzer die Tastenkombination des Befehls _execute_browser_action ändert, wird diese automatisch auf den Befehl _execute_action übertragen, wenn die Erweiterung von Manifest V2 auf V3 migriert. Dies wurde in Chrome 111 und Firefox 127 implementiert.

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

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

Werte der Tastenkombinationen

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

Tastenkombinationen

Hinweis: Auf Macs wird "Ctrl" als "Command" interpretiert. Wenn Sie tatsächlich "Ctrl" benötigen, geben Sie "MacCtrl" an.

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 AZ
    • die Zahlen 09
    • die Funktionstasten F1F12

      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.

Medientasten

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

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

Aktualisierung von Tastenkombinationen

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.

Beispiel

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

json
"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:

json
"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"
    }
  }
}

Browser-Kompatibilität

BCD tables only load in the browser