commands

Der commands Schlüssel 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 einer beliebigen Anzahl dieser Eigenschaften (alles Strings):

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

Der Wert jeder Eigenschaft ist die Tastenkombination für den Befehl auf dieser Plattform, dargestellt als ein String, der Tasten enthält, die durch + getrennt sind. 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 nicht aufgeführten Plattform eine Tastenkombination, es sei denn, ein Benutzer konfiguriert eine Verknüpfung oder durch die commands.update API.

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", zugänglich mit Ctrl + Shift + U unter 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 unter Linux, und keine Standardverknüpfung auf anderen Plattformen.
4. "do-nothing-yet", setzt keine Tastenkombination, ermöglicht aber, dass eine Verknüpfung vom Benutzer oder mit der commands.update API gesetzt wird.

Sie können den Befehlen mit 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 einen Toolbar-Button, der mit browserAction erstellt wurde oder in dem browser_action Schlüssel in der manifest.json angegeben ist.
• _execute_action: funktioniert wie ein Klick auf einen Toolbar-Button, der mit action erstellt wurde oder in dem action Schlüssel in der manifest.json angegeben ist.
• _execute_page_action: funktioniert wie ein Klick auf einen Adressleisten-Button, der mit pageAction erstellt wurde oder in dem page_action Schlüssel in der manifest.json angegeben ist.
• _execute_sidebar_action: öffnet die Erweiterung Seitenleiste, die im sidebar_action manifest.json Schlüssel angegeben ist.

Die Verfügbarkeit dieser speziellen Verknüpfungen 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 Verknüpfungstasten: als Tastenkombination oder als Medientaste.

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

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

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

3. Taste (verpflichtend). 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 Manage Extension Shortcuts zuweisen. Ihre Erweiterung kann diese Tasten nicht über die Manifestdatei 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 String angegeben, der die Menge der Tastenwerte enthält, in der oben genannten Reihenfolge, getrennt durch +. Zum Beispiel: "Ctrl+Shift+Z".

Wenn eine Tastenkombination bereits vom Browser (wie "Ctrl+P") oder von einem bestehenden 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 die Verknüpfung als eine dieser Medientasten angegeben werden:

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

In Firefox kann Ihre Erweiterung die Einstellungen der Verknüpfungstasten mit commands.update() aktualisieren. Benutzer können Verknüpfungen über die Manage Extension Shortcuts Option unter about:addons aktualisieren, wie in diesem Video gezeigt. Ihre Erweiterung kann diese Option mit commands.openShortcutSettings() öffnen.

In Chrome können Erweiterungen Verknüpfungstasten nicht programmgesteuert aktualisieren. Benutzer können Verknüpfungen unter chrome://extensions/shortcuts ändern, die mit tabs.create() geöffnet werden können.

Safari unterstützt weder die programmgesteuerte noch die Benutzermodifikation von Erweiterungs-Verknüpfungstasten.

Definieren Sie eine Tastenkombination mit nur der Standard-Tastenfolge:

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

Definieren Sie zwei Tastenkombinationen, eine mit einer plattformspezifischen Tastenfolge:

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