chrome.commands

refresh date: 2026-09-25 robots: noindex

Beschreibung

Mit der Commands API können Sie Tastenkombinationen hinzufü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 zu verwenden.

"commands"

Nutzung

Mit der Commands API können Entwickler von Erweiterungen bestimmte Befehle definieren und an eine Standard-Tastenkombination binden. Jeder Befehl, den eine Erweiterung akzeptiert, muss im Manifest der Erweiterung als Attribut des "commands"-Objekts deklariert werden.

Der Attributschlüssel wird als Name des Befehls verwendet. Befehlsobjekte können zwei Properties enthalten.

suggested_key

Eine optionale Property, die Standard-Tastenkombinationen für den Befehl deklariert. Wenn Sie den Befehl weglassen, wird er nicht gebunden. Diese Property 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. Wenn Sie plattformspezifische Tastenkombinationen angeben, sind die gültigen Objekteigenschaften default, chromeos, linux, mac und windows.

Weitere Informationen finden Sie unter Anforderungen an Tastenkombinationen.

description

Ein String, der dem Nutzer eine kurze Beschreibung des Zwecks des Befehls liefert. Dieser String wird in der Benutzeroberfläche für die Verwaltung von Tastenkombinationen für Erweiterungen angezeigt. Beschreibungen sind für Standardbefehle erforderlich, werden aber für Aktionsbefehle ignoriert.

Eine Erweiterung kann viele Befehle haben, aber maximal vier vorgeschlagene Tastenkombinationen angeben. Der Nutzer kann im Dialogfeld chrome://extensions/shortcuts manuell weitere Tastenkombinationen hinzufügen.

Unterstützte Schlüssel

Die folgenden Tasten sind verwendbare Befehlskürzel. Bei Schlüsseldefinitionen wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie versuchen, eine Erweiterung mit einem Schlüssel mit falscher Groß-/Kleinschreibung zu laden, führt dies bei der Installation zu einem Manifest-Parse-Fehler.

Alphatasten
A … Z
Zifferntasten
0 … 9
Standard-Schlüsselstrings

Allgemein – Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Pfeiltasten: Up, Down, Left, Right

Medientasten: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Modifikatortasten-Strings

Ctrl, Alt (Option unter macOS), Shift, MacCtrl (nur macOS), Command (nur macOS), Search (nur ChromeOS)

Anforderungen an Tastenkombinationen

  • Tastenkombinationen für Erweiterungsbefehle müssen entweder Ctrl oder Alt enthalten.

    • Modifikatoren können nicht in Kombination mit Medientasten verwendet werden.

  • Unter macOS wird Ctrl automatisch in Command umgewandelt.

    • Wenn Sie die Strg-Taste unter macOS verwenden möchten, ersetzen Sie beim Definieren der Tastenkombination "mac" die Taste Ctrl durch MacCtrl.

    • Wenn Sie MacCtrl in der Kombination für eine andere Plattform verwenden, führt dies zu einem Validierungsfehler und die Erweiterung kann nicht installiert werden.

  • Shift ist ein optionaler Modifikator auf allen Plattformen.

  • Search ist ein optionaler Modifikator, der nur für ChromeOS verfügbar ist.

  • Bestimmte Betriebssystem- und Chrome-Tastenkombinationen (z.B. für die Fensterverwaltung) haben immer Vorrang vor 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 mit 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 der Aktion, der Browseraktion bzw. der Seitenaktion reserviert. Diese Befehle senden keine command.onCommand-Ereignisse wie Standardbefehle.

Wenn Sie basierend auf dem Öffnen des Pop-ups Maßnahmen ergreifen müssen, können Sie im JavaScript des Pop-ups auf ein DOMContentLoaded-Ereignis warten.

Bereich

Standardmäßig gelten Befehle für den Chrome-Browser. Das bedeutet, dass Tastenkombinationen für Befehle inaktiv sind, wenn der Browser nicht im Fokus ist. Ab Chrome 35 können Entwickler von Erweiterungen einen Befehl optional als „global“ kennzeichnen. Globale Befehle funktionieren auch, wenn Chrome nicht im Fokus ist.

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 zulässig wäre, würde die Tastenkombination zum Öffnen eines Druckdialogs in anderen Anwendungen möglicherweise nicht funktionieren.

Endnutzer können globale Befehle über die Benutzeroberfläche unter chrome://extensions/shortcuts einer beliebigen Tastenkombination zuweisen.

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 werden die Hauptfunktionen der Commands API vorgestellt.

Grundlegender Befehl

Mit Befehlen können Erweiterungen Logik auf Tastenkombinationen abbilden, die vom Nutzer aufgerufen werden können. Im einfachsten Fall 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 Verwendung beschrieben, können Sie einen Befehl auch der Aktion einer Erweiterung zuordnen. Im folgenden Beispiel wird ein Inhaltsskript eingefügt, das eine Benachrichtigung 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 prüfen

Wenn eine Erweiterung versucht, eine Tastenkombination zu registrieren, die bereits von einer anderen Erweiterung verwendet wird, wird die Tastenkombination der zweiten Erweiterung nicht wie erwartet registriert. Sie können die Nutzerfreundlichkeit verbessern, indem Sie diese Möglichkeit vorhersehen und bei der Installation nach Konflikten suchen.

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (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

    Die Beschreibung des Erweiterungsbefehls

  • name

    String optional

    Der Name des Erweiterungsbefehls

  • verknüpfung

    String optional

    Die für diesen Befehl aktive Tastenkombination oder leer, wenn sie nicht aktiv ist.

Methoden

getAll()

Promise 
chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

Gibt alle registrierten Erweiterungsbefehle für diese Erweiterung und ihre Tastenkombination (falls aktiv) zurück. Vor Chrome 110 wurde _execute_action von diesem Befehl nicht zurückgegeben.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (commands: Command[]) => void

Ausgabe

  • Promise<Command[]>

    Chrome 96 oder höher

    Wird mit einer Liste der registrierten Befehle aufgelöst.

    Promises werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onCommand

chrome.commands.onCommand.addListener(
  callback: function,
)

Wird ausgelöst, wenn ein registrierter Befehl über eine Tastenkombination aktiviert wird.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (command: string, tab?: tabs.Tab) => void

    • Befehl

      String

    • Tabulatortaste

      tabs.Tab optional