browser.commands

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"

Concepten en 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 property van het object "commands" in het manifest van de extensie.

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

suggested_key

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

  • Een tekenreekswaarde geeft de standaardsneltoets 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 snelkoppelingen biedt, 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 te geven van het doel van de opdracht. 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 onjuiste hoofdletters, 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, Shift, MacCtrl (alleen macOS), Option (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 veel macOS-toetsenborden verwijst Alt naar de Option-toets.

    • Op macOS kun je ook Command of MacCtrl gebruiken in plaats van Ctrl, en de Option-toets in plaats van Alt (zie het volgende opsommingsteken).

  • Op macOS wordt Ctrl automatisch omgezet in Command.

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

    • Als je de Control-toets wilt gebruiken op macOS, 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:

browser.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 als de browser niet de focus heeft, de sneltoetsen voor opdrachten inactief zijn. 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 bijvoorbeeld Alt+P zou worden toegestaan als algemene sneltoets, werkt de sneltoets voor het openen van een afdrukdialoogvenster misschien niet in andere apps.

Eindgebruikers kunnen algemene opdrachten opnieuw toewijzen aan de gewenste toetsencombinatie via de UI 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:

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

Actieopdracht

Zoals beschreven in het gedeelte Concepten en gebruik kun je ook een opdracht 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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.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 te controleren op conflicten tijdens de installatie.

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

browser.commands.getAll(): 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.

Retourzendingen

  • Promise<Command[]>

    Chrome 96+ browser.* sinds Chrome 148

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

Evenementen

onCommand

browser.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