commands

Syntax

Der commands-Schlüssel ist ein Objekt, und jedes Kürzel ist eine Eigenschaft davon. Der Name der Eigenschaft ist der Name des Kürzels.

Der Wert jedes Kürzels ist ein Objekt mit bis zu 2 Eigenschaften:

1. suggested_key Optional: Die Tastenkombination, die das Kürzel aktiviert.
2. description Optional: Eine Zeichenkette, die das Kürzel beschreibt, d.h. was es tut.

Die suggested_key-Eigenschaft ist ein Objekt mit eventuell vorhandenen dieser Eigenschaften (alle als Strings):

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

Der Wert jeder Eigenschaft ist das Tastaturkürzel für den Befehl auf dieser Plattform, als String, der Tasten durch + getrennt enthält. 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 ein Tastaturkürzel, es sei denn, ein Kürzel wird vom Benutzer oder über 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": {}
}

Dieser JSON definiert diese Kürzel:

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 ohne Standardkürzel auf anderen Plattformen.
4. "do-nothing-yet", setzt kein Tastaturkürzel, aber ermöglicht das Setzen eines Kürzels vom Benutzer oder mit der commands.update API.

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

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

Spezielle Kürzel

Es gibt 4 spezielle Kürzel 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 oder im browser_action Schlüssel im manifest.json Schlüssel angegeben wurde.
• _execute_action: funktioniert wie ein Klick auf eine Toolbar-Schaltfläche, die mit action erstellt oder im action Schlüssel im manifest.json Schlüssel angegeben wurde.
• _execute_page_action: funktioniert wie ein Klick auf eine Adressleisten-Schaltfläche, die mit pageAction erstellt oder im page_action Schlüssel im manifest.json Schlüssel angegeben wurde.
• _execute_sidebar_action: öffnet die Sidebar der Erweiterung, die im sidebar_action manifest.json Schlüssel angegeben ist.

Die Verfügbarkeit dieser speziellen Kürzel variiert zwischen Manifest-Versionen und Browsern, wie folgt:

Zum Beispiel definiert dieses JSON eine Tastenkombination, die auf die Browser-Aktion der Erweiterung klickt:

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

Kürzelwerte

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

Tastenkombinationen

Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:

1. Modifier (verpflichtend, 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) einer von "Ctrl", "Alt", "Command", oder "MacCtrl" sein. Er darf nicht der Modifier sein, der bereits als Hauptmodifier verwendet wird.
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 zuordnen, indem sie Manage Extension Shortcuts verwenden. Ihre Erweiterung kann diese Tasten nicht aus der Manifest-Datei zuordnen. Sie kann sie jedoch mit commands.update zuordnen.

   • Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete, Up, Down, Left, Right

Die Taste wird dann als String angegeben, der die Tastenkombinationen in der oben aufgeführten Reihenfolge enthält, 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.

Medientasten

Alternativ kann das Kürzel als eine dieser Medientasten angegeben werden:

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

Kürzel aktualisieren

In Firefox kann Ihre Erweiterung die Einstellungen für Tastenkombinationen mit commands.update() aktualisieren. Benutzer können Kürzel über die Manage Extension Shortcuts Option bei about:addons aktualisieren, wie in diesem Video gezeigt. Ihre Erweiterung kann diese Option mit commands.openShortcutSettings() öffnen.

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

Safari unterstützt keine programmgesteuerte Änderung von Kürzeln für Erweiterungen. Ab Safari 26 können Benutzer die Kürzel einer Erweiterung in den Erweiterungseinstellungen von Safari ändern.

Beispiel

Definieren Sie ein Tastaturkürzel nur mit der Standard-Tastenkombination:

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

Definieren Sie zwei Tastaturkürzel, eines 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