chrome.commands

Beschreibung

Manifest

Konzepte und Verwendung

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

Der Property-Schlüssel wird als Name des Befehls verwendet. Befehlsobjekte können zwei Eigenschaften haben.

suggested_key

Eine optionale Eigenschaft, mit der Standard-Tastenkürzel für den Befehl deklariert werden. Wenn Sie das Flag weglassen, wird der Befehl nicht gebunden. Diese Eigenschaft kann entweder einen String oder einen Objektwert annehmen.

• Mit einem Stringwert wird die Standard-Tastenkombination angegeben, die auf allen Plattformen verwendet werden soll.

• Mit einem Objektwert kann der Entwickler der Erweiterung die Tastenkombination für jede Plattform anpassen. Wenn Sie platformspezifische Tastenkürzel angeben, sind default, chromeos, linux, mac und windows gültige Objektattribute.

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 zur Verwaltung von Tastenkürzeln 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. Der Nutzer kann über das Dialogfeld chrome://extensions/shortcuts weitere Verknüpfungen manuell hinzufügen.

Unterstützte Tasten

Die folgenden Tasten können als Befehlskürzel verwendet werden. Bei Schlüsseldefinitionen wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie versuchen, eine Erweiterung mit einem falsch formatierten Schlüssel zu laden, führt dies bei der Installation zu einem Manifest-Parsefehler.

Alphaschlüssel

A … Z

Zifferntaste

0 … 9

Standardschlüsselstrings

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

Richtungstasten Up, Down, Left, Right

Medientasten: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Strings für Modifikatortasten

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

Anforderungen an Tastenkombinationen

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

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

  • Auf vielen macOS-Tastaturen entspricht Alt der Optionstaste.

  • Unter macOS können auch Command oder MacCtrl anstelle von Ctrl oder 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 Taste „Befehl“ zu verweisen.

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

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

• Shift ist ein optionaler Modifikator auf allen Plattformen.

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

• Bestimmte Tastenkürzel für das Betriebssystem und Chrome (z.B. Fensterverwaltung) haben immer Vorrang vor Tastenkürzeln 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 jedem im Manifest definierten Befehl einen Handler binden, indem Sie onCommand.addListener verwenden. 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 jeweils für das Auslösen Ihrer Aktion, Browseraktion oder Seitenaktion reserviert. Diese Befehle senden keine command.onCommand-Ereignisse wie Standardbefehle.

Wenn Sie aufgrund des Öffnens des Pop-ups eine Aktion ausführen müssen, können Sie im JavaScript des Pop-ups auf das Ereignis DOMContentLoaded warten.

Umfang

Standardmäßig sind Befehle auf den Chrome-Browser beschränkt. Das bedeutet, dass die Tastenkürzel für Befehle inaktiv sind, wenn der Browser nicht den Fokus hat. Ab Chrome 35 können Entwickler von Erweiterungen einen Befehl optional als „global“ kennzeichnen. Globale Befehle funktionieren auch, wenn Chrome nicht den 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 Tastenkürzel in anderen Anwendungen überschrieben werden. Wenn beispielsweise Alt+P als global zugelassen würde, funktioniert die Tastenkombination zum Öffnen eines Druckdialogfelds in anderen Anwendungen möglicherweise nicht.

Endnutzer können globale Befehle über die Benutzeroberfläche unter chrome://extensions/shortcuts auf ihre bevorzugte Tastenkombination umlegen.

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

Grundlegender Befehl

Mit Befehlen können Erweiterungen Logik Tastenkombinationen zuordnen, die vom Nutzer aufgerufen werden können. Im einfachsten Fall erfordert ein Befehl nur eine Befehlsdeklaration im Manifest der Erweiterung und eine Listenerregistrierung, 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 Konzepte und Verwendung beschrieben, können Sie auch einen Befehl der Aktion einer Erweiterung zuordnen. Im folgenden Beispiel wird ein Inhaltsskript eingefügt, das auf der aktuellen Seite eine Benachrichtigung 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, einen Tastenkürzel zu registrieren, der bereits von einer anderen Erweiterung verwendet wird, wird das Tastenkürzel der zweiten Erweiterung nicht wie erwartet registriert. Sie können die Nutzerfreundlichkeit verbessern, indem Sie diese Möglichkeit berücksichtigen und bei der Installation auf Kollisionen prüfen.

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,
)