commands

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

Der Wert jeder Verknüpfung ist ein Objekt mit bis zu 2 Eigenschaften:

1. suggested_key Optional: die Kombination von Tasten, die die Verknüpfung aktiviert.
2. description Optional: ein String, der die Verknüpfung beschreibt, d.h. was sie 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 die Tastenkombination für den Befehl auf dieser Plattform, als String, der Tasten enthält, getrennt durch "+". Der Wert von "default" wird auf allen Plattformen verwendet, die nicht explizit aufgeführt sind. Wenn "default" nicht enthalten ist, hat der Befehl auf keiner Plattform eine Tastenkombination, es sei denn, es wird vom Benutzer oder über die commands.update API eine Tastenkombination 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 Verknüpfungen:

1. "toggle-feature", erreichbar mit Ctrl + Shift + U unter 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 unter Linux und keine Standardverknüpfung auf anderen Plattformen.
4. "do-nothing-yet", legt keine Tastenkombination fest, ermöglicht aber dem Benutzer, eine Verknüpfung zu setzen oder mit der commands.update API.

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

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

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

• _execute_browser_action: Funktioniert wie ein Klick auf eine Symbolleistenschaltfläche, die mit browserAction erstellt wurde oder im Schlüssel browser_action in der manifest.json angegeben ist.
• _execute_action: Funktioniert wie ein Klick auf eine Symbolleistenschaltfläche, die mit action erstellt wurde oder im Schlüssel action in der manifest.json angegeben ist.
• _execute_page_action: Funktioniert wie ein Klick auf eine Adressleistenschaltfläche, die mit pageAction erstellt wurde oder im Schlüssel page_action in der manifest.json angegeben ist.
• _execute_sidebar_action: Öffnet die Seitenleiste der Erweiterung, die im Schlüssel sidebar_action in der manifest.json angegeben ist.

Die Verfügbarkeit dieser speziellen Verknüpfungen variiert je nach Manifest-Versionen und Browsern, wie folgt:

Zum Beispiel definiert dieses JSON eine Tastenkomination, die wie ein Klick auf die Browseraktion der Erweiterung wirkt:

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

Es gibt zwei gültige Formate für Verknüpfungstasten: als Tastenkombination oder als Media-Taste.

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

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

2. Sekundärer Modifikator (optional). Falls vorhanden, muss dies entweder "Shift" oder (für Firefox ≥ 63) einer von "Ctrl", "Alt", "Command" oder "MacCtrl" sein. Darf nicht der bereits als Hauptmodifikator verwendete Modifikator sein.

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

   • die Buchstaben A – Z
   • die Zahlen 0 – 9
   • die Funktionstasten F1 – F12
   • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

Die Taste wird dann als String angegeben, der die Reihe von Tastenwerten enthält, in der obigen Reihenfolge, getrennt durch "+". Zum Beispiel, "Ctrl+Shift+Z".

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

Alternativ kann die Verknüpfung als eine der folgenden Media-Tasten angegeben werden:

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

Verknüpfungen können über commands.update() aktualisiert werden. Benutzer können auch Verknüpfungen über die Option „Erweiterungsverknüpfungen verwalten“ in about:addons in Firefox aktualisieren, wie in diesem Video gezeigt. In Chrome können Benutzer Verknüpfungen unter chrome://extensions/shortcuts ändern.

Definieren Sie eine einzelne Tastenkombination, die nur die Standardtastenkombination verwendet:

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

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