chrome.commands

Beschrijving

Gebruik de opdrachten-API om sneltoetsen toe te voegen die acties in uw extensie activeren, bijvoorbeeld een actie om de browseractie te openen of een opdracht naar de extensie te sturen.

Manifest

De volgende sleutels moeten in het manifest worden gedeclareerd om deze API te kunnen gebruiken.

"commands"

Concepten en gebruik

Met de Commands API kunnen extensie-ontwikkelaars specifieke opdrachten definiëren en deze aan een standaard toetsencombinatie koppelen. Elke opdracht die een extensie accepteert, moet worden gedeclareerd als eigenschappen van het object "commands" in het manifest van de extensie .

De eigenschapssleutel wordt gebruikt als de naam van de opdracht. Commandoobjecten kunnen twee eigenschappen hebben.

suggested_key

Een optionele eigenschap die standaardsneltoetsen voor de opdracht declareert. Als u dit weglaat, is de opdracht ongebonden. 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 extensie-ontwikkelaar de sneltoets voor elk platform aanpassen. Bij het aanbieden van platformspecifieke snelkoppelingen zijn geldige objecteigenschappen default , chromeos , linux , mac en windows .

Zie Toetscombinatievereisten voor aanvullende details.

description

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

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

Ondersteunde sleutels

De volgende toetsen zijn bruikbare opdrachtsnelkoppelingen. Sleuteldefinities zijn hoofdlettergevoelig. Als u probeert een extensie te laden met een sleutel met een onjuiste behuizing, resulteert dit tijdens de installatie in een manifeste parseerfout.

Alfatoetsen
A … Z
Numerieke toetsen
0 … 9
Standaard sleutelkoorden

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

Pijltjestoetsen - Up , Down , Left , Right

Mediatoetsen– MediaNextTrack , MediaPlayPause , MediaPrevTrack , MediaStop

Wijzigingssleutelreeksen

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

Vereisten voor toetscombinaties

  • Sneltoetsen voor extensieopdrachten moeten Ctrl of Alt bevatten.

    • Modifiers kunnen niet worden gebruikt in combinatie met mediatoetsen.

  • Op macOS wordt Ctrl automatisch omgezet in Command .

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

    • Het gebruik van MacCtrl in de combinatie voor een ander platform zal een validatiefout veroorzaken en voorkomen dat de extensie wordt geïnstalleerd.

  • Shift is een optionele modifier op alle platforms.

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

  • Bepaalde besturingssysteem- en Chrome-snelkoppelingen (bijvoorbeeld vensterbeheer) hebben altijd voorrang op extensie-opdrachtsnelkoppelingen en kunnen niet worden overschreven.

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

service-werker.js:

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

Actie-opdrachten

De opdrachten _execute_action (Manifest V3), _execute_browser_action (Manifest V2) en _execute_page_action (Manifest V2) zijn gereserveerd voor de actie om respectievelijk uw actie, browseractie of paginaactie 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 te luisteren naar een DOMContentLoaded- gebeurtenis in het JavaScript van uw pop-up.

Domein

Standaard zijn opdrachten gericht op de Chrome-browser. Dit betekent dat wanneer de browser geen focus heeft, de opdrachtsnelkoppelingen inactief zijn. Vanaf Chrome 35 kunnen ontwikkelaars van extensies een opdracht optioneel markeren als 'algemeen'. Globale opdrachten werken ook als Chrome geen focus heeft.

Suggesties voor toetsenbordsneltoetsen 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, aangezien als bijvoorbeeld Alt+P als globaal zou worden toegestaan, de sneltoets voor het openen van een afdrukdialoogvenster mogelijk niet werkt in andere toepassingen.

Eindgebruikers zijn vrij om globale opdrachten opnieuw toe te wijzen aan de toetscombinatie van hun voorkeur met behulp van 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 verruimen de kernfunctionaliteit van de Commands API.

Basis commando

Met opdrachten kunnen extensies logica toewijzen aan sneltoetsen die door de gebruiker kunnen worden aangeroepen. In principe vereist een opdracht alleen een opdrachtdeclaratie in het manifest van de extensie en een luisteraarregistratie, zoals weergegeven 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-werker.js:

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

Actie commando

Zoals beschreven in de sectie Gebruik , kunt u een opdracht ook toewijzen aan de actie van een extensie. In het volgende voorbeeld wordt een inhoudsscript geïnjecteerd 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-werker.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 op deze mogelijkheid te anticiperen en tijdens de installatie te controleren op botsingen.

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

Soorten

Command

Eigenschappen

  • beschrijving

    tekenreeks optioneel

    De beschrijving van de extensieopdracht

  • naam

    tekenreeks optioneel

    De naam van de extensieopdracht

  • snelkoppeling

    tekenreeks optioneel

    De snelkoppeling die actief is voor deze opdracht, of leeg als deze niet actief is.

Methoden

getAll()

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

Retourneert alle geregistreerde extensieopdrachten voor deze extensie en hun snelkoppeling (indien actief). Vóór Chrome 110 retourneerde deze opdracht _execute_action niet.

Parameters

  • Bel terug

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (commands: Command[])=>void

Geeft terug

  • Beloof < Commando []>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

Evenementen

onCommand

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

Wordt geactiveerd wanneer een geregistreerde opdracht wordt geactiveerd met behulp van een sneltoets.

Parameters

  • Bel terug

    functie

    De callback parameter ziet er als volgt uit: 

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