chrome.commands

Beschreibung

Verwenden Sie die Befehls-API, um Tastenkombinationen hinzuzufü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 verwenden zu können.

"commands"

Konzepte und Verwendung

Mit der Commands API können Erweiterungsentwickler bestimmte Befehle definieren und an eine Standardeinstellung binden. Tastenkombination. Jeder von einer Erweiterung akzeptierte Befehl muss als Eigenschaften des "commands"-Objekt im Manifest der Erweiterung.

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. Bei Auslassung wird der Parameter -Befehl wird nicht gebunden. Diese Eigenschaft kann entweder einen String oder einen Objektwert annehmen.

• Ein Stringwert gibt die Standard-Tastenkombination an, die auf allen Plattformen.

• Mit einem Objektwert kann der Entwickler der Erweiterung die Tastenkombination für jede Erweiterung individuell anpassen. Plattform. Bei der Angabe plattformspezifischer Tastenkombinationen sind default gültige Objektattribute. chromeos, linux, mac und windows.

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 auf der Benutzeroberfläche zur Verwaltung von Tastenkombinationen angezeigt. Beschreibungen sind für Standard- für Aktionsbefehle, werden aber ignoriert.

Eine Erweiterung kann viele Befehle enthalten, aber maximal vier vorgeschlagene Tastenkombinationen. Die Nutzer kann über das Dialogfeld „chrome://extensions/shortcuts“ manuell weitere Verknüpfungen hinzufügen.

Unterstützte Schlüssel

Die folgenden Tasten sind verwendbare Tastenkombinationen. Bei wichtigen Definitionen wird zwischen Groß- und Kleinschreibung unterschieden. Es wird versucht, Wenn eine Erweiterung mit einem Schlüssel mit falscher Groß- und Kleinschreibung geladen wird, führt das zu einem Manifest-Parsing-Fehler unter Installationszeit.

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)

Hinweis:Tab wurde aus Gründen der Barrierefreiheit aus der Liste der unterstützten Schlüssel in Chrome 33 entfernt.

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 bei der Definition von "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 bestimmten Tastenkombinationen Tastenkombinationen für Erweiterungsbefehle und können nicht überschrieben werden.

Hinweis: Tastenkombinationen, die Ctrl+Alt enthalten, sind nicht zulässig, um Konflikte mit den AltGr-Taste.

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 einen Handler an jeden der im Manifest definierten Befehle binden. mit onCommand.addListener. Beispiel:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Aktionsbefehle

_execute_action (Manifest V3), _execute_browser_action (Manifest V2) und _execute_page_action-Befehle (Manifest V2) sind für das Auslösen Ihrer Aktion reserviert. Browseraktion bzw. Seitenaktion. Diese Befehle erstellen keine command.onCommand-Ereignisse wie Standardbefehle.

Wenn Sie beim Öffnen eines Pop-ups Maßnahmen ergreifen müssen, sollten Sie auf eine DOMContentLoaded-Ereignis im JavaScript-Code des Pop-ups.

Umfang

Standardmäßig werden Befehle dem Chrome-Browser zugeordnet. Wenn der Browser keine Fokus haben, die Tastenkombinationen für Befehle sind inaktiv. Ab Chrome 35 können Entwickler von Erweiterungen können Sie einen Befehl als „global“ markieren. Globale Befehle funktionieren auch, wenn Chrome keinen Fokus hat.

Hinweis:ChromeOS unterstützt keine globalen Befehle.

Vorschläge für Tastenkombinationen für globale Befehle sind auf Ctrl+Shift+[0..9] beschränkt. Dies ist ein Schutzmaßnahme zur Minimierung des Risikos, dass Tastenkombinationen in anderen Anwendungen überschrieben werden, Alt+P sollte z. B. global zugelassen sein, die Tastenkombination zum Öffnen eines Druckdialogfelds. funktioniert möglicherweise nicht in anderen Anwendungen.

Endnutzer können globale Befehle mithilfe der exponierten UI ihrer bevorzugten Tastenkombination ändern. um chrome://extensions/shortcuts.

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. In ihrer Ein Befehl erfordert lediglich eine Befehlsdeklaration im Manifest der Erweiterung und einen Listener 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 Nutzung beschrieben, können Sie auch dem Code einer Erweiterung einen Befehl zuordnen. Aktion ausführen. Im folgenden Beispiel wird ein Inhaltsskript eingefügt, das ein Benachrichtigung auf der aktuellen Seite, wenn der Nutzer entweder auf die Aktion der Erweiterung klickt oder die .

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 Verknüpfung zu registrieren, die bereits von einer anderen Erweiterung verwendet wird, Das Kürzel der zweiten Erweiterung wird nicht wie erwartet registriert. Sie können einen robusteren Endnutzer bereitstellen, indem sie diese Möglichkeit vorhersehen 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.
    }
  });
}

Typen

Command

Attribute

• Beschreibung

  String optional

  Beschreibung des Erweiterungsbefehls

• Name

  String optional

  Der Name des Erweiterungsbefehls

• verknüpfung

  String optional

  Die für diesen Befehl aktive Tastenkombination. Wenn sie nicht aktiv ist, ist das Feld leer.

Methoden

getAll()

<ph type="x-smartling-placeholder"></ph> Versprechen

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

Gibt alle registrierten Erweiterungsbefehle für diese Erweiterung und die zugehörige Tastenkombination (falls aktiv) zurück. Vor Chrome 110 hat dieser Befehl nicht _execute_action zurückgegeben.

Parameter

• callback

  Funktion optional

  Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

  (commands: Command[]) => void

  • commands

    Befehl[]

Gibt Folgendes zurück:

• Promise<Befehl[]>

  Chrome 96 und höher

  Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

Ereignisse

onCommand

chrome.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: <ph type="x-smartling-placeholder"></ph>

  (command: string, tab?: tabs.Tab) => void

  • befehl

    String

  • Tabulatortaste

    tabs.Tab optional