chrome.commands

Beschrijving

Manifest

Begrippen en gebruik

Met de Commands API kunnen extensieontwikkelaars specifieke commando's definiëren en deze koppelen aan een standaardtoetsencombinatie. Elk commando dat een extensie accepteert, moet worden gedeclareerd als eigenschap van het object "commands" in het manifest van de extensie .

De eigenschapssleutel wordt gebruikt als opdrachtnaam. Opdrachtobjecten kunnen twee eigenschappen hebben.

suggested_key

Een optionele eigenschap die de standaardsneltoetsen voor de opdracht aangeeft. Indien weggelaten, is de opdracht niet gebonden. Deze eigenschap kan een tekenreeks of een objectwaarde aannemen.

• Een tekenreekswaarde specificeert de standaardsneltoets die op alle platforms moet worden gebruikt.

• Met een objectwaarde kan de extensieontwikkelaar de sneltoets voor elk platform aanpassen. Bij het opgeven van platformspecifieke sneltoetsen zijn de geldige objecteigenschappen default , chromeos , linux , mac en windows .

Zie Vereisten voor toetscombinaties voor meer informatie.

description

Een tekenreeks die de gebruiker een korte beschrijving van het doel van de opdracht geeft. Deze tekenreeks wordt weergegeven in de gebruikersinterface voor het beheer van sneltoetsen voor extensies. Beschrijvingen zijn vereist voor standaardopdrachten, maar worden genegeerd voor actieopdrachten .

Een extensie kan veel opdrachten bevatten, maar mag maximaal vier sneltoetsen voorstellen. De gebruiker kan handmatig meer sneltoetsen toevoegen via het dialoogvenster chrome://extensions/shortcuts .

Ondersteunde sleutels

De volgende toetsen zijn bruikbare sneltoetsen. Toetsdefinities zijn hoofdlettergevoelig. Pogingen om een extensie te laden met een sleutel met een onjuiste hoofdletter/kleine letter, resulteren in een manifest parse error tijdens de installatie.

Alfa-toetsen

A … Z

Numerieke toetsen

0 … 9

Standaard sleutelreeksen

Algemeen – Comma , Period , Home , End , PageUp , PageDown , Space , Insert , Delete

Pijltjestoetsen – Up , Down , Left , Right

Mediatoetsen – MediaNextTrack , MediaPlayPause , MediaPrevTrack , MediaStop

Modifier-toetsreeksen

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

Vereisten voor toetscombinaties

• Sneltoetsen voor extensieopdrachten moeten Ctrl of Alt bevatten.

  • Modifiers kunnen niet in combinatie met mediatoetsen worden gebruikt.

  • Op veel macOS-toetsenborden verwijst Alt naar de Option-toets.

  • Op macOS kunt u ook Command of MacCtrl gebruiken in plaats van Ctrl of Alt (zie het volgende opsommingsteken).

• Op macOS wordt Ctrl automatisch omgezet naar Command .

  • Command kan ook gebruikt worden in de "mac" -snelkoppeling om expliciet te verwijzen naar de Command-toets.

  • Om de Control-toets op macOS te gebruiken, vervangt u Ctrl door MacCtrl wanneer u de "mac" -sneltoets definieert.

  • Als u MacCtrl gebruikt in de combinatie voor een ander platform, treedt er een validatiefout op en kan de extensie niet worden geïnstalleerd.

• Shift is een optionele modifier op alle platforms.

• Search is een optionele modifier die exclusief is voor ChromeOS.

• Bepaalde snelkoppelingen van het besturingssysteem en Chrome (bijvoorbeeld vensterbeheer) hebben altijd voorrang op snelkoppelingen van Extensies en kunnen niet worden overschreven.

Afhandelen van opdrachtgebeurtenissen

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 uw service worker kunt u een handler koppelen aan elk van de opdrachten die in het manifest zijn gedefinieerd met behulp van onCommand.addListener . Bijvoorbeeld:

service-worker.js:

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

Actiecommando's

De opdrachten _execute_action (Manifest V3), _execute_browser_action (Manifest V2) en _execute_page_action (Manifest V2) zijn gereserveerd voor respectievelijk de actie om uw actie, browseractie of pagina-actie te activeren. Deze opdrachten verzenden geen command.onCommand- gebeurtenissen zoals standaardopdrachten.

Als u actie moet ondernemen op basis van het openen van uw pop-up, kunt u overwegen om te luisteren naar een DOMContentLoaded -gebeurtenis in de JavaScript van uw pop-up.

Domein

Standaard zijn opdrachten beperkt tot de Chrome-browser. Dit betekent dat snelkoppelingen voor opdrachten inactief zijn wanneer de browser geen focus heeft. Vanaf Chrome 35 kunnen extensieontwikkelaars een opdracht optioneel markeren als 'globaal'. Globale opdrachten werken ook wanneer Chrome geen focus heeft.

Suggesties voor sneltoetsen voor globale opdrachten zijn beperkt tot Ctrl+Shift+[0..9] . Dit is een beschermende maatregel om het risico te minimaliseren dat sneltoetsen in andere toepassingen worden overschreven. Als bijvoorbeeld Alt+P als globale opdracht zou worden toegestaan, werkt de sneltoets voor het openen van een afdrukdialoog mogelijk niet in andere toepassingen.

Eindgebruikers kunnen globale opdrachten naar eigen voorkeur opnieuw toewijzen aan hun favoriete toetsencombinatie met behulp van de gebruikersinterface die beschikbaar is op chrome://extensions/shortcuts .

Voorbeeld:

manifest.json:

{
  "name": "My extension",
  ...
  "commands": {
    "toggle-feature-foo": {
      "suggested_key": {
        "default": "Ctrl+Shift+5"
      },
      "description": "Toggle feature foo",
      "global": true
    }
  },
  ...
}

Voorbeelden

De volgende voorbeelden illustreren de kernfunctionaliteit van de Commands API.

Basiscommando

Met commando's kunnen extensies logica koppelen aan sneltoetsen die door de gebruiker kunnen worden aangeroepen. In de meest basale vorm vereist een commando alleen een commandodeclaratie in het manifest van de extensie en een listenerregistratie, zoals in het volgende voorbeeld.

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

Actiecommando

Zoals beschreven in de sectie Concepten en gebruik , kunt u ook een opdracht toewijzen aan een actie van een extensie. Het volgende voorbeeld injecteert een contentscript dat een waarschuwing op de huidige pagina weergeeft wanneer de gebruiker op de actie van de extensie klikt of de sneltoets activeert.

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

Controleer geregistreerde opdrachten

Als een extensie probeert een snelkoppeling te registreren die al door een andere extensie wordt gebruikt, wordt de snelkoppeling van de tweede extensie niet zoals verwacht geregistreerd. U kunt een robuustere eindgebruikerservaring bieden door rekening te houden met deze mogelijkheid en tijdens de installatie te controleren op conflicten.

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