browser.commands

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"

Konzepte und Verwendung

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 als Attribut 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. Wenn Sie ihn weglassen, wird der Befehl nicht gebunden. Diese Property kann entweder einen String oder einen Objektwert annehmen.

  • Ein Stringwert gibt die Standardtastenkombination 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 default, chromeos, linux, mac und windows gültige Objekteigenschaften.

    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 Verknüpfungen 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, Shift, MacCtrl (nur macOS), Option (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.

    • Auf vielen macOS-Tastaturen bezieht sich Alt auf die Wahltaste.

    • Unter macOS können auch Command oder MacCtrl anstelle von Ctrl und die Taste Option anstelle von Alt verwendet werden (siehe nächster Punkt).

  • Unter macOS wird Ctrl automatisch in Command umgewandelt.

    • Command kann auch in der Tastenkombination "mac" verwendet werden, um explizit auf die Befehlstaste zu verweisen.

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

    • 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 Tastenkombinationen des Betriebssystems und von Chrome (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:

browser.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 oder der Seitenaktion reserviert. Diese Befehle lösen keine command.onCommand-Ereignisse wie Standardbefehle aus.

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 Befehlskombinationen inaktiv sind, wenn der Browser nicht im Fokus ist. Ab Chrome 35 können Entwickler von Erweiterungen einen Befehl optional als „global“ markieren. 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 ihrer bevorzugten 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:

browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" triggered`);
});

Aktionsbefehl

Wie im Abschnitt Konzepte und Verwendung beschrieben, können Sie einen Befehl auch einer 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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

Registrierte Befehle prüfen

Wenn eine Erweiterung versucht, ein Tastenkürzel zu registrieren, das bereits von einer anderen Erweiterung verwendet wird, wird das Tastenkürzel der zweiten Erweiterung nicht wie erwartet registriert. Sie können eine robustere Endnutzererfahrung bieten, indem Sie diese Möglichkeit antizipieren und bei der Installation nach Konflikten suchen.

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

browser.commands.getAll(): 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.

Ausgabe

  • Promise<Command[]>

    Chrome 96+ browser.* seit Chrome 148

    Wird mit einer Liste der registrierten Befehle aufgelöst.

Ereignisse

onCommand

browser.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