chrome.commands

Beschrijving

Manifest

Concepten en gebruik

De Commands API stelt ontwikkelaars van extensies in staat om specifieke commando's te definiëren en deze te koppelen aan een standaard toetsencombinatie. Elk commando dat een extensie accepteert, moet worden gedeclareerd als eigenschap van het "commands" -object in het manifest van de extensie .

De eigenschapssleutel wordt gebruikt als naam voor de opdracht. Opdrachtobjecten kunnen twee eigenschappen hebben.

suggested_key

Een optionele eigenschap die de standaard sneltoetsen voor de opdracht definieert. Indien deze eigenschap wordt weggelaten, is de opdracht niet toegewezen. Deze eigenschap kan een tekenreeks of een objectwaarde accepteren.

• Een tekenreeks geeft de standaard sneltoets aan die op alle platforms moet worden gebruikt.

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

  Zie de vereisten voor de sleutelcombinatie voor meer informatie.

description

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

Een extensie kan veel commando's bevatten, maar mag maximaal vier voorgestelde sneltoetsen opgeven. De gebruiker kan handmatig meer sneltoetsen toevoegen via het dialoogvenster chrome://extensions/shortcuts .

Ondersteunde sleutels

De volgende toetsen zijn bruikbare sneltoetsen. Toetsdefinities zijn hoofdlettergevoelig. Als u een extensie probeert te laden met een toets met een onjuiste hoofdlettergebruik, resulteert dit in een manifestparseerfout tijdens de installatie.

Alfabetische sleutels

A … Z

Numerieke toetsen

0 … 9

Standaard toetsenreeksen

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

Pijltoetsen – Up , Down , Left , Right

Mediatoetsen – MediaNextTrack , MediaPlayPause , MediaPrevTrack , MediaStop

Modificatietoetsreeksen

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

Belangrijkste combinatievereisten

• Sneltoetsen voor extensieopdrachten moeten Ctrl of Alt bevatten.

  • Modificatietoetsen kunnen niet in combinatie met mediatoetsen worden gebruikt.

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

  • Op macOS kunnen Command of MacCtrl ook worden gebruikt in plaats van Ctrl , en de Option -toets kan worden gebruikt in plaats van Alt (zie volgende opsomming).

• Op macOS wordt Ctrl automatisch omgezet in Command .

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

  • Om de Control-toets op macOS te gebruiken, vervang je Ctrl door MacCtrl bij het definiëren van de sneltoets voor "mac" .

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

• Shift is een optionele modifier op alle platformen.

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

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

Verwerk commando-evenementen

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 je service worker kun je aan elk van de commando's die in het manifest zijn gedefinieerd een handler koppelen met behulp van onCommand.addListener . Bijvoorbeeld:

service-worker.js:

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

Actieopdrachten

De commando's _execute_action (Manifest V3), _execute_browser_action (Manifest V2) en _execute_page_action (Manifest V2) zijn gereserveerd voor respectievelijk het activeren van uw actie, browseractie of pagina-actie. Deze commando's verzenden geen command.onCommand- gebeurtenissen zoals standaardcommando's.

Als je actie moet ondernemen zodra je pop-up opent, kun je overwegen om in de JavaScript-code van je pop-up te luisteren naar een DOMContentLoaded -gebeurtenis.

Domein

Standaard zijn commando's beperkt tot de Chrome-browser. Dit betekent dat commando-sneltoetsen niet actief zijn wanneer de browser niet actief is. Vanaf Chrome 35 kunnen ontwikkelaars van extensies een commando optioneel als 'globaal' markeren. Globale commando's werken ook wanneer Chrome niet actief is.

De suggesties voor sneltoetsen voor globale opdrachten zijn beperkt tot Ctrl+Shift+[0..9] . Dit is een beschermingsmaatregel om het risico te minimaliseren dat sneltoetsen in andere toepassingen worden overschreven. Als bijvoorbeeld Alt+P als globale sneltoets zou worden toegestaan, zou de sneltoets voor het openen van een afdrukdialoogvenster mogelijk niet meer werken in andere toepassingen.

Eindgebruikers kunnen globale commando's naar eigen voorkeur toewijzen aan een toetsencombinatie via de gebruikersinterface 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 demonstreren de kernfunctionaliteit van de Commands API.

Basiscommando

Met commando's kunnen extensies logica koppelen aan sneltoetsen die door de gebruiker kunnen worden geactiveerd. In de meest eenvoudige vorm vereist een commando alleen een commandodeclaratie in het manifest van de extensie en een registratie van een listener, zoals in het volgende voorbeeld wordt getoond.

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

Actieopdracht

Zoals beschreven in het gedeelte 'Concepten en gebruik' , kunt u ook een opdracht koppelen aan een actie van een extensie. Het volgende voorbeeld voegt een script toe dat een melding 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 of de commando's geregistreerd zijn.

Als een extensie een snelkoppeling probeert te registreren die al door een andere extensie wordt gebruikt, wordt de snelkoppeling van de tweede extensie niet correct geregistreerd. U kunt een robuustere gebruikerservaring bieden door op deze mogelijkheid te anticiperen 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,
)