Beschreibung
Verwenden Sie die Befehls-API, um Tastenkombinationen hinzuzufügen, die Aktionen in Ihrer Erweiterung auslösen, z. B. eine Aktion zum Öffnen der Browseraktion oder zum Senden eines Befehls an die Erweiterung.
Manifest
Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API verwenden zu können.
"commands"
Konzepte und Verwendung
Mit der Commands API können Erweiterungsentwickler bestimmte Befehle definieren und an eine Standardschlüsselkombination binden. Jeder von einer Erweiterung akzeptierte Befehl muss als Attribute des "commands"
-Objekts im Manifest der Erweiterung deklariert werden.
Der Attributschlüssel wird als Name des Befehls verwendet. Befehlsobjekte können zwei Attribute haben.
suggested_key
Eine optionale Eigenschaft, die Standard-Tastenkombinationen für den Befehl deklariert. Ohne Angabe wird die Bindung des Befehls aufgehoben. Diese Eigenschaft kann entweder einen String oder einen Objektwert annehmen.
Ein Stringwert gibt die Standard-Tastenkombination an, die auf allen Plattformen verwendet werden soll.
Mit einem Objektwert kann der Entwickler der Erweiterung die Tastenkombination für jede Plattform anpassen. Bei der Angabe plattformspezifischer Tastenkombinationen sind
default
,chromeos
,linux
,mac
undwindows
gültige Objektattribute.
Weitere Informationen finden Sie unter Anforderungen an Schlüsselkombinationen.
description
Ein String, der dem Nutzer eine kurze Beschreibung des Zwecks des Befehls liefert. Dieser String wird in der Benutzeroberfläche zur Verwaltung von Tastenkombinationen für Erweiterungen angezeigt. Beschreibungen sind für Standardbefehle erforderlich, werden für Aktionsbefehle jedoch ignoriert.
Eine Erweiterung kann viele Befehle enthalten, aber maximal vier vorgeschlagene Tastenkombinationen. Der Nutzer kann über das Dialogfeld chrome://extensions/shortcuts
weitere Verknüpfungen manuell hinzufügen.
Unterstützte Schlüssel
Die folgenden Tasten sind verwendbare Tastenkombinationen. Bei wichtigen Definitionen wird zwischen Groß- und Kleinschreibung unterschieden. Der Versuch, eine Erweiterung mit einem falsch formatierten Schlüssel zu laden, führt bei der Installation zu einem Manifest-Parsing-Fehler.
- Alphatasten
A
...Z
- Numerische Schlüssel
0
...9
- Standardschlüsselstrings
Allgemein–
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
Pfeiltasten –
Up
,Down
,Left
,Right
Medientasten:
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
,MediaStop
- Zeichenfolgen der Modifikatortasten
Ctrl
,Alt
(Option
unter macOS),Shift
,MacCtrl
(nur macOS),Command
(nur macOS),Search
(nur ChromeOS)
Anforderungen an Tastenkombination
Tastenkombinationen für Erweiterungsbefehle müssen entweder
Ctrl
oderAlt
enthalten.- Modifikatoren können nicht in Kombination mit Medientasten verwendet werden.
Unter macOS wird
Ctrl
automatisch inCommand
konvertiert.Wenn Sie unter macOS die Strg-Taste verwenden möchten, ersetzen Sie beim Definieren des Tastenkürzels
"mac"
Ctrl
durchMacCtrl
.Die Verwendung von
MacCtrl
in der Kombination für eine andere Plattform führt zu einem Validierungsfehler und verhindert, dass die Erweiterung installiert wird.
Shift
ist ein optionaler Modifikator auf allen Plattformen.Search
ist ein optionaler Modifikator exklusiv für ChromeOS.Bestimmte Tastenkombinationen für Betriebssysteme und Chrome (z.B. für die Fensterverwaltung) haben immer Vorrang vor den Tastenkombinationen für Erweiterungsbefehle und können nicht überschrieben werden.
Befehlsereignisse verarbeiten
manifest.json:
{
"name": "My extension",
...
"commands": {
"run-foo": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y"
},
"description": "Run \"foo\" on the current page."
},
"_execute_action": {
"suggested_key": {
"windows": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y",
"chromeos": "Ctrl+Shift+U",
"linux": "Ctrl+Shift+J"
}
}
},
...
}
In Ihrem Service Worker können Sie mithilfe von onCommand.addListener
einen Handler an jeden der im Manifest definierten Befehle binden. Beispiel:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
Aktionsbefehle
Die Befehle _execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) und _execute_page_action
(Manifest V2) sind für das Auslösen Ihrer Aktion, Browseraktion oder Seitenaktion reserviert. Diese Befehle geben keine command.onCommand-Ereignisse wie Standardbefehle aus.
Wenn Sie Aktionen beim Öffnen des Pop-ups ausführen möchten, sollten Sie im JavaScript-Code des Pop-ups auf ein DOMContentLoaded-Ereignis warten.
Bereich
Standardmäßig werden Befehle dem Chrome-Browser zugeordnet. Das bedeutet, dass die Tastenkürzel der Befehle inaktiv sind, wenn der Browser keinen Fokus hat. Ab Chrome 35 können Erweiterungsentwickler einen Befehl optional als „global“ kennzeichnen. Globale Befehle funktionieren auch, wenn Chrome keinen Fokus hat.
Vorschläge für Tastenkombinationen für globale Befehle sind auf Ctrl+Shift+[0..9]
beschränkt. Dies ist eine Schutzmaßnahme, um das Risiko zu minimieren, dass Tastenkombinationen in anderen Anwendungen überschrieben werden. Wenn beispielsweise Alt+P
als global zugelassen ist, funktioniert die Tastenkombination zum Öffnen eines Druckdialogfelds möglicherweise in anderen Anwendungen nicht.
Endnutzer können globale Befehle über die UI unter chrome://extensions/shortcuts
ihrer bevorzugten Tastenkombination zuordnen.
Beispiel:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
Beispiele
In den folgenden Beispielen wird die Hauptfunktion der Commands API angepasst.
Basisbefehl
Mithilfe von Befehlen können Erweiterungen Logikverknüpfungen zuordnen, die vom Nutzer aufgerufen werden können. Im Grunde erfordert ein Befehl nur eine Befehlsdeklaration im Manifest der Erweiterung und eine Listener-Registrierung, wie im folgenden Beispiel gezeigt.
manifest.json:
{
"name": "Command demo - basic",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"commands": {
"inject-script": {
"suggested_key": "Ctrl+Shift+Y",
"description": "Inject a script on the page"
}
}
}
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" triggered`);
});
Aktionsbefehl
Wie im Abschnitt Nutzung beschrieben, können Sie der Aktion einer Erweiterung auch einen Befehl zuordnen. Im folgenden Beispiel wird ein Inhaltsskript eingefügt, das eine Warnung auf der aktuellen Seite anzeigt, wenn der Nutzer entweder auf die Aktion der Erweiterung klickt oder die Tastenkombination auslöst.
manifest.json:
{
"name": "Commands demo - action invocation",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"permissions": ["activeTab", "scripting"],
"action": {},
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+U",
"mac": "Command+U"
}
}
}
}
service-worker.js:
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
func: contentScriptFunc,
args: ['action'],
});
});
function contentScriptFunc(name) {
alert(`"${name}" executed`);
}
// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" called`);
});
Registrierte Befehle zum Überprüfen
Wenn eine Erweiterung versucht, eine Verknüpfung zu registrieren, die bereits von einer anderen Erweiterung verwendet wird, wird die Verknüpfung der zweiten Erweiterung nicht wie erwartet registriert. Du kannst für eine stabilere Endnutzererfahrung sorgen, wenn du diese Möglichkeit vorhersiehst und bei der Installation auf Konflikte prüfst.
service-worker.js:
chrome.runtime.onInstalled.addListener((details) => {
if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
checkCommandShortcuts();
}
});
// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
chrome.commands.getAll((commands) => {
let missingShortcuts = [];
for (let {name, shortcut} of commands) {
if (shortcut === '') {
missingShortcuts.push(name);
}
}
if (missingShortcuts.length > 0) {
// Update the extension UI to inform the user that one or more
// commands are currently unassigned.
}
});
}
Typen
Command
Attribute
-
Beschreibung
String optional
Beschreibung des Erweiterungsbefehls
-
name
String optional
Der Name des Erweiterungsbefehls
-
verknüpfung
String optional
Die für diesen Befehl aktive Tastenkombination. Ist sie nicht aktiv, ist das Feld leer.
Methoden
getAll()
chrome.commands.getAll(
callback?: function,
)
Gibt alle registrierten Erweiterungsbefehle für diese Erweiterung und die zugehörige Tastenkombination (falls aktiv) zurück. Vor Chrome 110 hat dieser Befehl nicht _execute_action
zurückgegeben.
Parameter
Rückgabe
-
Promise<Befehl[]>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.