chrome.commands

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik de API voor opdrachten om sneltoetsen toe te voegen die acties in je 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 gedefinieerd om deze API te gebruiken.

"commands"

Gebruik

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

De property-sleutel wordt gebruikt als de naam van de opdracht. Opdrachtobjecten kunnen 2 property's hebben.

suggested_key

Een optionele eigenschap die standaardsneltoetsen voor de opdracht definieert. Als je dit weglaat, wordt de opdracht niet gebonden. Deze property kan een tekenreeks of een objectwaarde hebben.

  • Een tekenreekswaarde 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. Als je platformspecifieke sneltoetsen invoert, zijn de geldige objecteigenschappen default, chromeos, linux, mac en windows.

Ga naar Vereisten voor toetscombinaties voor meer informatie.

description

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

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

Ondersteunde sleutels

De volgende toetsen zijn bruikbare sneltoetsen voor opdrachten. Sleuteldefinities zijn hoofdlettergevoelig. Als je een extensie probeert te laden met een sleutel met een onjuiste hoofdletter, leidt dit tot een manifestparseerfout tijdens de installatie.

Alfabetische toetsen
A … Z
Numerieke toetsen
0 … 9
Standaard sleutelreeksen

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

Pijltoetsen: Up, Down, Left, Right

Mediatoetsen: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Tekenreeksen voor functietoetsen

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

Vereisten voor toetsencombinaties

  • Sneltoetsen voor extensieopdrachten moeten Ctrl of Alt bevatten.

    • Modificatietoetsen kunnen niet worden gebruikt in combinatie met mediatoetsen.

  • Op macOS wordt Ctrl automatisch omgezet in Command.

    • Als je de Control-toets op macOS wilt gebruiken, vervang je Ctrl door MacCtrl als je de sneltoets "mac" definieert.

    • Als je MacCtrl gebruikt in de combinatie voor een ander platform, leidt dit tot een validatiefout en kan de extensie niet worden geïnstalleerd.

  • Shift is een optionele modifier op alle platforms.

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

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

Opdrachtgebeurtenissen verwerken

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 servicemedewerker kun je een handler binden aan elk van de opdrachten die in het manifest zijn gedefinieerd met onCommand.addListener. Voorbeeld:

service-worker.js:

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

Actieopdrachten

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

Als je actie moet ondernemen op basis van het openen van je pop-up, kun je luisteren naar een DOMContentLoaded-gebeurtenis in het JavaScript van je pop-up.

Bereik

Opdrachten zijn standaard gericht op de Chrome-browser. Dit betekent dat opdrachttoetsen inactief zijn als de browser niet de focus heeft. Vanaf Chrome 35 kunnen extensieontwikkelaars een opdracht optioneel markeren als globaal. Algemene opdrachten werken ook als Chrome niet de focus heeft.

Suggesties voor sneltoetsen voor algemene opdrachten zijn beperkt tot Ctrl+Shift+[0..9]. Dit is een beschermende maatregel om het risico te minimaliseren dat sneltoetsen in andere apps worden overschreven. Als Alt+P bijvoorbeeld als algemeen wordt toegestaan, werkt de sneltoets om een afdrukdialoogvenster te openen misschien niet in andere apps.

Eindgebruikers kunnen globale opdrachten opnieuw toewijzen aan de gewenste toetsencombinatie via de UI die wordt getoond 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 tonen de kernfunctionaliteit van de Commands API.

Basisopdracht

Met opdrachten kunnen extensies logica toewijzen aan sneltoetsen die door de gebruiker kunnen worden aangeroepen. In de meest eenvoudige vorm vereist een opdracht alleen een opdrachtdeclaratie 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`);
});

Actieopdracht

Zoals beschreven in het gedeelte Gebruik kun je een opdracht ook toewijzen aan de actie van een extensie. In het volgende voorbeeld wordt een contentscript geïnjecteerd dat een melding op de huidige pagina toont als 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`);
});

Geregistreerde opdrachten verifiëren

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

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (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

Eigenschappen

  • beschrijving

    tekenreeks optioneel

    De beschrijving van de extensieopdracht

  • name

    tekenreeks optioneel

    De naam van de extensieopdracht

  • snelkoppeling

    tekenreeks optioneel

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

Methoden

getAll()

Promise 
chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

Retourneert alle geregistreerde extensieopdrachten voor deze extensie en de bijbehorende sneltoets (indien actief). Vóór Chrome 110 retourneerde deze opdracht geen _execute_action.

Parameters

  • callback

    functie optioneel

    De parameter callback ziet er zo uit: 

    (commands: Command[]) => void

Retourzendingen

  • Promise<Command[]>

    Chrome 96+

    Voert de omzetting uit met een lijst met de geregistreerde opdrachten.

    Promises worden alleen ondersteund voor Manifest V3 en hoger. Andere platforms moeten callbacks gebruiken.

Evenementen

onCommand

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

Wordt geactiveerd als een geregistreerde opdracht wordt geactiveerd met een sneltoets.

Parameters

  • callback

    functie

    De parameter callback ziet er zo uit: 

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

    • opdracht

      tekenreeks

    • tab

      tabs.Tab optioneel