commands

Syntax

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 Tastenkombination, die die Verknüpfung aktiviert.
2. description Optional: ein String, der die Verknüpfung beschreibt, d.h. was sie tut.

Die suggested_key Eigenschaft ist ein Objekt mit diesen 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 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 keine Tastenkombination auf Plattformen, die nicht enthalten sind, es sei denn, eine Verknüpfung wird vom Benutzer oder durch die commands.update API 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", wird mit Ctrl + Shift + U auf Linux aufgerufen und mit Alt + Shift + U auf allen anderen Plattformen.
2. "do-another-thing", wird mit Ctrl + Shift + Y auf allen Plattformen aufgerufen.
3. "do-something-else", wird mit Ctrl + Shift + P nur auf Linux aufgerufen und hat keine Standardverknüpfung auf anderen Plattformen.
4. "do-nothing-yet", setzt keine Tastenkombination, ermöglicht aber eine Verknüpfung, die vom Benutzer oder mit der commands.update API festgelegt werden kann.

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

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

Spezielle Verknüpfungen

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 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 Adressleisten-Schaltfläche, die mit pageAction erstellt wurde oder im page_action Schlüssel in der manifest.json angegeben ist.
• _execute_sidebar_action: öffnet die Sidebar der Erweiterung, die im sidebar_action manifest.json-Schlüssel angegeben ist.

Die Verfügbarkeit dieser speziellen Verknüpfungen variiert zwischen Manifestversionen und Browsern, wie folgt:

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

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

Verknüpfungswerte

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

Tastenkombinationen

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

1. Modifier (erforderlich, außer für Funktionstasten). Dies kann einer der folgenden sein: "Ctrl", "Alt", "Command" oder "MacCtrl".
2. Sekundärer Modifier (optional). Falls angegeben, muss dies entweder "Shift" sein oder (für Firefox ≥ 63) einer von "Ctrl", "Alt", "Command" oder "MacCtrl". Darf nicht der Modifier sein, der bereits als Hauptmodifier verwendet wird.
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 Tasten F13 bis F19 einer Erweiterung mit Manage Extension Shortcuts zuweisen. Ihre Erweiterung kann diese Tasten nicht aus der 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 Zeichenfolge angegeben, die die Reihe von Tastenwerten enthält, in der oben aufgeführten 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 sie nicht überschreiben. Sie können sie definieren, aber Ihr Ereignishandler wird nicht aufgerufen, wenn der Benutzer die Tastenkombination drückt.

Mediensteuerungstasten

Alternativ kann die Verknüpfung als eine der folgenden Mediensteuerungstasten angegeben werden:

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

Aktualisieren von Verknüpfungen

In Firefox kann Ihre Erweiterung die Einstellungen für Verknüpfungstasten mithilfe von commands.update() aktualisieren. Benutzer können Verknüpfungen mit der Option Manage Extension Shortcuts bei 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, was mit tabs.create() geöffnet werden kann.

Safari unterstützt weder die programmgesteuerte noch die Benutzeränderung von Erweiterungsverknüpfungstasten.

Beispiel

Definieren Sie eine Tastenkombination nur mit der Standardtastenkombination:

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

Browser-Kompatibilität