chrome.commands

Beschreibung

Manifest

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 und windows 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 oder Alt enthalten.

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

• Unter macOS wird Ctrl automatisch in Command konvertiert.

  • Wenn Sie unter macOS die Strg-Taste verwenden möchten, ersetzen Sie beim Definieren des Tastenkürzels "mac" Ctrl durch MacCtrl.

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

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

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