commands
Typ | Object |
---|---|
Verpflichtend | Nein |
Manifestversion | 2 oder höher |
Beispiel |
json
|
Verwenden Sie den commands
Schlüssel, um eine oder mehrere Tastenkombinationen für Ihre Erweiterung zu definieren.
Jede Tastenkombination wird mit einem Namen, einer Kombination von Tasten und einer Beschreibung definiert. Nachdem Sie Befehle im manifest.json
Ihrer Erweiterung definiert haben, können Sie mit der commands
API auf deren zugehörige Tastenkombinationen hören.
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:
suggested_key
Optional: die Tastenkombination, die die Verknüpfung aktiviert.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:
"toggle-feature"
, wird mit Ctrl + Shift + U auf Linux aufgerufen und mit Alt + Shift + U auf allen anderen Plattformen."do-another-thing"
, wird mit Ctrl + Shift + Y auf allen Plattformen aufgerufen."do-something-else"
, wird mit Ctrl + Shift + P nur auf Linux aufgerufen und hat keine Standardverknüpfung auf anderen Plattformen."do-nothing-yet"
, setzt keine Tastenkombination, ermöglicht aber eine Verknüpfung, die vom Benutzer oder mit dercommands.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 mitbrowserAction
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 mitaction
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 mitpageAction
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:
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 Verknüpfung des _execute_browser_action
Befehls ändert, wird diese automatisch auf den _execute_action
Befehl übernommen, wenn die Erweiterung von Manifest V2 zu V3 migriert. Dies wurde in Chrome 111 und Firefox 127 implementiert.
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
Hinweis:
Auf Macs wird "Ctrl"
als "Command"
interpretiert, daher, wenn Sie tatsächlich "Ctrl"
benötigen, geben Sie "MacCtrl"
an.
Tastenkombinationen müssen aus 2 oder 3 Tasten bestehen:
- Modifier (erforderlich, außer für Funktionstasten). Dies kann einer der folgenden sein:
"Ctrl"
,"Alt"
,"Command"
oder"MacCtrl"
. - 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. - 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
bisF19
einer Erweiterung mit Manage Extension Shortcuts zuweisen. Ihre Erweiterung kann diese Tasten nicht aus der Manifestdatei zuweisen. Sie kann sie jedoch mitcommands.update
zuweisen. Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
,Up
,Down
,Left
,Right
- die Buchstaben
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"
}
}
}