commands
Typ | Object |
---|---|
Verpflichtend | Nein |
Manifest-Version | 2 oder höher |
Beispiel |
json
|
Nutzen Sie den Schlüssel commands
, um eine oder mehrere Tastenkombinationen für Ihre Erweiterung zu definieren.
Jede Tastenkombination wird durch einen Namen, eine Tastenkombination und eine Beschreibung definiert. Nachdem Sie in der Datei manifest.json
Ihrer Erweiterung Befehle definiert haben, können Sie auf die entsprechenden Tastenkombinationen mit der commands
API reagieren.
Syntax
Der Schlüssel commands
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:
suggested_key
Optional: die Tastenkombination, die die Tastenkombination aktiviert.description
Optional: ein String, der die Tastenkombination beschreibt, d. h. was sie macht.
Die Eigenschaft suggested_key
ist ein Objekt mit beliebigen oder keinen dieser Eigenschaften (alle als Strings):
"default"
"mac"
"linux"
"windows"
"chromeos"
"android"
"ios"
Der Wert jeder Eigenschaft ist die Tastenkombination für den Befehl auf dieser Plattform, angegeben als String mit durch "+
" getrennten Tasten. 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 Plattform, die nicht ausgeschlossen wurde, eine Tastenkombination, es sei denn, sie wird vom Benutzer oder durch die commands.update
API konfiguriert.
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 folgende Tastenkombinationen:
"toggle-feature"
: erreichbar mit Ctrl + Shift + U auf Linux und Alt + Shift + U auf allen anderen Plattformen."do-another-thing"
: erreichbar mit Ctrl + Shift + Y auf allen Plattformen."do-something-else"
: erreichbar mit Ctrl + Shift + P nur auf Linux und ohne Standard-Tastenkombination auf anderen Plattformen."do-nothing-yet"
: setzt keine Tastenkombination, erlaubt jedoch dem Benutzer oder dercommands.update
API, eine Tastenkombination festzulegen.
Sie können auf diese Befehle mithilfe eines Codes wie diesem reagieren, hier für den Befehl "toggle-feature"
:
browser.commands.onCommand.addListener((command) => {
if (command === "toggle-feature") {
console.log("Toggling the feature!");
}
});
Spezielle Tastenkombinationen
Es gibt 4 spezielle Tastenkombinationen mit Standardaktionen, bei denen das commands.onCommand
-Ereignis nicht ausgelöst wird:
_execute_browser_action
: funktioniert wie ein Klick auf eine Werkzeugleisten-Schaltfläche, die mitbrowserAction
erstellt oder im browser_action-Schlüssel der manifest.json-Datei angegeben wurde._execute_action
: funktioniert wie ein Klick auf eine Werkzeugleisten-Schaltfläche, die mitaction
erstellt oder im action-Schlüssel der manifest.json-Datei angegeben wurde._execute_page_action
: funktioniert wie ein Klick auf eine Adressleisten-Schaltfläche, die mitpageAction
erstellt oder im page_action-Schlüssel der manifest.json-Datei angegeben wurde._execute_sidebar_action
: öffnet die Seitenleiste der Erweiterung, die im sidebar_action-Schlüssel der manifest.json-Datei angegeben ist.
Die Verfügbarkeit dieser speziellen Tastenkombinationen variiert je nach Manifest-Version und Browser, wie folgt:
Manifest V2 | Manifest V3 | |
---|---|---|
_execute_browser_action |
Ja | Nein |
_execute_action |
Nein | Ja |
_execute_page_action |
Ja | Nur Firefox |
_execute_sidebar_action |
Nur Firefox | Nur Firefox |
Hinweis:
Wenn der Benutzer die Tastenkombination des Befehls _execute_browser_action
ändert, wird diese automatisch auf den Befehl _execute_action
übertragen, wenn die Erweiterung von Manifest V2 auf V3 migriert. Dies wurde in Chrome 111 und Firefox 127 implementiert.
Beispiel: Dieses JSON definiert eine Tastenkombination, die die Schaltfläche der Browser-Aktion der Erweiterung anklickt:
"commands": {
"_execute_browser_action": {
"suggested_key": {
"default": "Ctrl+Shift+Y"
}
}
}
Werte der Tastenkombinationen
Es gibt zwei gültige Formate für Tastenkombinationen: als Tastenkombination oder als Medientaste.
Tastenkombinationen
Hinweis:
Auf Macs wird "Ctrl"
als "Command"
interpretiert. Wenn Sie tatsächlich "Ctrl"
benötigen, geben Sie "MacCtrl"
an.
Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:
-
Modifikationstaste (obligatorisch, außer bei Funktionstasten). Dies kann eine der folgenden sein:
"Ctrl"
,"Alt"
,"Command"
oder"MacCtrl"
. -
Sekundäre Modifikationstaste (optional). Falls angegeben, muss diese entweder
"Shift"
sein oder (für Firefox ≥ 63) eine der folgenden:"Ctrl"
,"Alt"
,"Command"
oder"MacCtrl"
. Sie darf nicht dieselbe Modifikationstaste sein wie die Hauptmodifikationstaste. -
Schlüssel (obligatorisch). 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
bisF19
einer Erweiterung über Erweiterungskürzel verwalten zuweisen. Ihre Erweiterung kann diese Tasten nicht über die Manifestdatei zuweisen, jedoch mitcommands.update
. Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
,Up
,Down
,Left
,Right
- die Buchstaben
Der Schlüssel wird dann als String angegeben, der die Reihe der Tastenwerte enthält, in der oben beschriebenen Reihenfolge, getrennt durch "+
", z. B. "Ctrl+Shift+Z"
.
Wenn eine Tastenkombination bereits vom Browser (z. B. "Ctrl+P"
) oder von einer bestehenden Erweiterung verwendet wird, können Sie sie nicht überschreiben. Sie können sie definieren, jedoch wird Ihr Ereignishandler nicht aufgerufen, wenn der Benutzer die Tastenkombination drückt.
Medientasten
Alternativ kann die Kombination als eine der folgenden Medientasten angegeben werden:
"MediaNextTrack"
"MediaPlayPause"
"MediaPrevTrack"
"MediaStop"
Aktualisierung von Tastenkombinationen
Tastenkombinationen können mit commands.update()
aktualisiert werden. Benutzer können Tastenkombinationen auch über die Option "Erweiterungskürzel verwalten" in about:addons
in Firefox aktualisieren, wie in diesem Video dargestellt. In Chrome können Benutzer Tastenkombinationen unter chrome://extensions/shortcuts
ändern.
Beispiel
Definieren Sie eine einzige 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 plattformabhängigen 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
BCD tables only load in the browser