chrome.commands

Beschreibung

Manifest

Konzepte und Nutzung

Mit der Commands API können Erweiterungsentwickler bestimmte Befehle definieren und an eine Standardschlüsselkombination binden. Jeder von einer Erweiterung akzeptierte Befehl muss als Eigenschaften des "commands"-Objekts im Manifest der Erweiterung deklariert werden.

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

suggested_key

Eine optionale Eigenschaft, die Standard-Tastenkürzel für den Befehl angibt. Wenn keine Angabe gemacht wird, wird die Bindung des Befehls aufgehoben. Diese Eigenschaft kann entweder einen String oder einen Objektwert annehmen.

• Mit einem Stringwert wird die standardmäßige Tastenkombination angegeben, die auf allen Plattformen verwendet werden sollte.

• Mit einem Objektwert kann der Entwickler der Erweiterung die Tastenkombination für jede Plattform anpassen. Gültige Objekteigenschaften für plattformspezifische Verknüpfungen sind default, chromeos, linux, mac und windows.

Weitere Informationen finden Sie unter Anforderungen an Schlüsselkombinationen.

description

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

Eine Erweiterung kann viele Befehle enthalten, aber höchstens vier vorgeschlagene Tastenkombinationen angeben. Der Nutzer kann über das Dialogfeld chrome://extensions/shortcuts manuell weitere Verknüpfungen hinzufügen.

Unterstützte Schlüssel

Die folgenden Tasten sind nutzbare Tastenkombinationen für Befehle. Bei Schlüsseldefinitionen wird zwischen Groß- und Kleinschreibung unterschieden. Der Versuch, eine Erweiterung mit einem Schlüssel mit falscher Groß-/Kleinschreibung 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

Medienschlüssel: 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 konvertiert.

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

  • Wenn du MacCtrl in Kombination für eine andere Plattform verwendest, wird ein Validierungsfehler ausgegeben und die Erweiterung kann nicht installiert werden.

• Shift ist ein optionaler Modifikator auf allen Plattformen.

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

• Bestimmte Tastenkombinationen von Betriebssystem und Chrome (z.B. 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 Ihrer Aktion, Browseraktion bzw. Seitenaktion reserviert. Diese Befehle lösen keine command.onCommand-Ereignisse wie Standardbefehle aus.

Wenn Sie basierend auf dem Öffnen des Pop-ups bestimmte Aktionen durchführen müssen, sollten Sie im JavaScript-Code des Pop-ups auf ein DOMContentLoaded-Ereignis warten.

Umfang

Standardmäßig sind Befehle auf den Chrome-Browser beschränkt. Das bedeutet, dass Befehlskürzel inaktiv sind, wenn der Browser keinen Fokus hat. Ab Chrome 35 können Entwickler von Erweiterungen Befehle 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 Vorsichtsmaßnahme, um das Risiko des Überschreibens von Tastenkombinationen in anderen Anwendungen zu minimieren. Sollte beispielsweise Alt+P als global zulässig sein, funktioniert die Tastenkombination zum Öffnen eines Druckdialogfelds in anderen Anwendungen möglicherweise nicht.

Endnutzer können globale Befehle über die UI unter chrome://extensions/shortcuts ihrer bevorzugten Tastenkombination neu 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 erläutert.

Basisbefehl

Mithilfe von Befehlen können Erweiterungen Logik Tastenkombinationen 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 auch einen Befehl 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 das Tastenkürzel 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 ü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. Wenn Sie diese Möglichkeit antizipieren und bei der Installation prüfen möchten, ob Kollisionen möglich sind, können Sie den Nutzern eine bessere Erfahrung bieten.

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.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
)

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