chrome.commands

Beschreibung

Manifest

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)

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.

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.

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

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

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