commands

Der commands Schlüssel 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 tut.

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

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

Der Wert jeder Eigenschaft ist die Tastenkombination für den Befehl auf dieser Plattform, als eine Zeichenkette, die 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 keine Tastenkombination auf einer nicht enthaltenen Plattform, es sei denn, ein Benutzer oder die commands.update API konfiguriert eine Tastenkombination.

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

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 keine Standard-Tastenkombination auf anderen Plattformen.
4. "do-nothing-yet", setzt keine Tastenkombination, ermöglicht es jedoch, eine Tastenkombination durch den Benutzer oder mit der commands.update API einzurichten.

Sie können auf die Befehle mit einem solchen Code hören, 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 besondere Tastenkombinationen mit Standardaktionen, für die das commands.onCommand Ereignis nicht ausgelöst wird:

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

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

Zum Beispiel definiert dieses JSON eine Tastenkombination, die auf die Browseraktion der Erweiterung klickt:

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

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

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

1. Modifier (erforderlich, außer bei Funktionstasten). Dies kann einer der folgenden sein: "Ctrl", "Alt", "Command", oder "MacCtrl".
2. Sekundärer Modifier (optional). Wenn angegeben, muss dies entweder "Shift" oder (für Firefox ≥ 63) eine der folgenden Angaben sein: "Ctrl", "Alt", "Command", oder "MacCtrl". Darf nicht der bereits als Hauptmodifier verwendete Modifier sein.
3. Taste (erforderlich). 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 F13 bis F19 Tasten einer Erweiterung mithilfe der Option Manage Extension Shortcuts zuweisen. 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 Zeichenkette angegeben, die die Gruppe von Tasteneingaben in der oben genannten Reihenfolge enthält, getrennt durch +. Beispielsweise "Ctrl+Shift+Z".

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

Alternativ kann die Tastenkombination als eine dieser Media-Tasten angegeben werden:

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

In Firefox kann Ihre Erweiterung die Tastenkombinationseinstellungen mit commands.update() aktualisieren. Benutzer können Tastenkombinationen mithilfe der Option Manage Extension Shortcuts unter about:addons aktualisieren, wie in diesem Video gezeigt. Ihre Erweiterung kann diese Option mit commands.openShortcutSettings() öffnen.

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

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

Definieren Sie eine 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 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"
    }
  }
}