chrome.commands

Beschreibung

Manifest

Konzepte und Verwendung

Mit der Commands API können Erweiterungsentwickler bestimmte Befehle definieren und sie an eine Standardtastenkombination 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 Eigenschaften haben.

suggested_key

Eine optionale Eigenschaft, mit der Standardtastenkombinationen für den Befehl deklariert werden. Wenn er weggelassen wird, ist der Befehl nicht gebunden. Diese Eigenschaft 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 Erweiterungsentwickler den Tastenkürzel für jede Plattform anpassen. Wenn Sie plattformspezifische Verknüpfungen 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 höchstens vier vorgeschlagene Tastenkombinationen. Der Nutzer kann über das Dialogfeld chrome://extensions/shortcuts manuell weitere Tastenkombinationen hinzufügen.

Unterstützte Schlüssel

Die folgenden Tasten können als Befehlsverknüpfungen verwendet werden. Bei Schlüsseldefinitionen wird zwischen Groß- und Kleinschreibung unterschieden. Wenn Sie versuchen, eine Erweiterung mit einem Schlüssel zu laden, bei dem die Groß- und Kleinschreibung nicht korrekt ist, führt dies bei der Installation zu einem Manifest-Parsing-Fehler.

Alphaschlüssel

A … Z

Zifferntasten

0 … 9

Standardschlüssel-Strings

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

Pfeiltasten: Up, Down, Left, Right

Medientasten – MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Strings für Modifikatortasten

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

Anforderungen an Tastenkombinationen

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

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

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

  • Unter macOS können anstelle von Ctrl auch Command oder MacCtrl verwendet werden. Anstelle von Alt kann die Option-Taste verwendet werden (siehe nächster Aufzählungspunkt).

• 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 Ctrl-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 das zu einem Validierungsfehler und die Erweiterung kann nicht installiert werden.

• Shift ist auf allen Plattformen ein optionaler Modifikator.

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

• Bestimmte Betriebssystem- und Chrome-Tastenkürzel (z.B. für die 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 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. Mit diesen Befehlen werden keine command.onCommand-Ereignisse wie bei Standardbefehlen gesendet.

Wenn Sie Maßnahmen ergreifen müssen, nachdem das Pop-up-Fenster geöffnet wurde, sollten Sie in Ihrem Pop-up-JavaScript auf ein DOMContentLoaded-Ereignis warten.

Umfang

Standardmäßig beziehen sich Befehle auf den Chrome-Browser. Das bedeutet, dass Befehls-Shortcuts inaktiv sind, wenn der Browser nicht im Fokus ist. Ab Chrome 35 können Erweiterungsentwickler 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 Druckdialogfelds in anderen Anwendungen möglicherweise nicht funktionieren.

Endnutzer können globale Befehle über die unter chrome://extensions/shortcuts verfügbare Benutzeroberfläche 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 wird die Kernfunktionalität der Commands API demonstriert.

Einfacher Befehl

Mit Befehlen können Erweiterungen Logik Tastenkombinationen zuordnen, die vom Nutzer aufgerufen werden können. Im einfachsten Fall ist für einen Befehl nur eine Befehlsdeklaration im Manifest der Erweiterung und eine Listener-Registrierung erforderlich, 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 einer Erweiterungsaktion zuordnen. Im folgenden Beispiel wird ein Content-Script eingefügt, das auf der aktuellen Seite eine Benachrichtigung anzeigt, wenn der Nutzer entweder auf die Erweiterungsaktion klickt oder den 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 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 Endnutzererfahrung 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(): Promise<Command[]>

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