chrome.commands

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API Commands per aggiungere scorciatoie da tastiera che attivano azioni nell'estensione, ad esempio un'azione per aprire l'azione del browser o inviare un comando all'estensione.

Manifest

Per utilizzare questa API, le seguenti chiavi devono essere dichiarate nel file manifest.

"commands"

Utilizzo

L'API Commands consente agli sviluppatori di estensioni di definire comandi specifici e associarli a una combinazione di tasti predefinita. Ogni comando accettato da un'estensione deve essere dichiarato come proprietà dell'oggetto "commands" nel manifest dell'estensione.

La chiave della proprietà viene utilizzata come nome del comando. Gli oggetti comando possono accettare due proprietà.

suggested_key

Una proprietà facoltativa che dichiara le scorciatoie da tastiera predefinite per il comando. Se omesso, il comando non verrà associato. Questa proprietà può assumere un valore stringa o un valore oggetto.

  • Un valore stringa specifica la scorciatoia da tastiera predefinita da utilizzare su tutte le piattaforme.

  • Un valore oggetto consente allo sviluppatore dell'estensione di personalizzare la scorciatoia da tastiera per ogni piattaforma. Quando fornisci scorciatoie specifiche per la piattaforma, le proprietà degli oggetti valide sono default, chromeos, linux, mac e windows.

Per ulteriori dettagli, consulta i requisiti per le combinazioni di tasti.

description

Una stringa utilizzata per fornire all'utente una breve descrizione dello scopo del comando. Questa stringa viene visualizzata nell'interfaccia utente di gestione delle scorciatoie da tastiera dell'estensione. Le descrizioni sono obbligatorie per i comandi standard, ma vengono ignorate per i comandi di azione.

Un'estensione può avere molti comandi, ma può specificare al massimo quattro scorciatoie da tastiera suggerite. L'utente può aggiungere manualmente altre scorciatoie dalla finestra di dialogo chrome://extensions/shortcuts.

Chiavi supportate

I seguenti tasti sono scorciatoie per i comandi utilizzabili. Le definizioni delle chiavi sono sensibili alle maiuscole. Il tentativo di caricare un'estensione con una chiave con un uso delle maiuscole errato comporterà un errore di analisi del manifest al momento dell'installazione.

Chiavi alpha
A … Z
Tasti numerici
0 … 9
Stringhe di chiavi standard

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

Tasti Freccia: Up, Down, Left, Right

Tasti multimediali: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Stringhe dei tasti di modifica

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

Requisiti per le combinazioni di tasti

  • Le scorciatoie dei comandi delle estensioni devono includere Ctrl o Alt.

    • I modificatori non possono essere utilizzati in combinazione con i tasti multimediali.

  • Su macOS, Ctrl viene convertito automaticamente in Command.

    • Per utilizzare il tasto Ctrl su macOS, sostituisci Ctrl con MacCtrl quando definisci la scorciatoia "mac".

    • L'utilizzo di MacCtrl nella combinazione per un'altra piattaforma causerà un errore di convalida e impedirà l'installazione dell'estensione.

  • Shift è un modificatore facoltativo su tutte le piattaforme.

  • Search è un modificatore facoltativo esclusivo di ChromeOS.

  • Alcune scorciatoie del sistema operativo e di Chrome (ad es. la gestione delle finestre) hanno sempre la priorità sulle scorciatoie dei comandi delle estensioni e non possono essere sovrascritte.

Gestione degli eventi di comando

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"
      }
    }
  },
  ...
}

Nel service worker, puoi associare un gestore a ciascuno dei comandi definiti nel manifest utilizzando onCommand.addListener. Ad esempio:

service-worker.js:

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

Comandi di azione

I comandi _execute_action (Manifest V3), _execute_browser_action (Manifest V2) e _execute_page_action (Manifest V2) sono riservati rispettivamente all'attivazione dell'azione, dell'azione del browser o dell'azione della pagina. Questi comandi non inviano eventi command.onCommand come i comandi standard.

Se devi intraprendere un'azione in base all'apertura del popup, ti consigliamo di ascoltare un evento DOMContentLoaded all'interno del codice JavaScript del popup.

Ambito

Per impostazione predefinita, i comandi hanno come ambito il browser Chrome. Ciò significa che quando il browser non è attivo, le scorciatoie dei comandi non sono attive. A partire da Chrome 35, gli sviluppatori di estensioni possono facoltativamente contrassegnare un comando come "globale". I comandi globali funzionano anche quando Chrome non è attivo.

I suggerimenti per le scorciatoie da tastiera per i comandi globali sono limitati a Ctrl+Shift+[0..9]. Si tratta di una misura di protezione per ridurre al minimo il rischio di eseguire l'override delle scorciatoie in altre applicazioni, poiché se, ad esempio, Alt+P fosse consentito come globale, la scorciatoia da tastiera per l'apertura di una finestra di dialogo di stampa potrebbe non funzionare in altre applicazioni.

Gli utenti finali sono liberi di rimappare i comandi globali alla combinazione di tasti che preferiscono utilizzando l'interfaccia utente esposta all'indirizzo chrome://extensions/shortcuts.

Esempio:

manifest.json:

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

Esempi

I seguenti esempi mostrano la funzionalità di base dell'API Commands.

Comando di base

I comandi consentono alle estensioni di mappare la logica alle scorciatoie da tastiera che possono essere richiamate dall'utente. Nella sua forma più semplice, un comando richiede solo una dichiarazione nel manifest dell'estensione e la registrazione di un listener, come mostrato nell'esempio seguente.

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

Comando di azione

Come descritto nella sezione Utilizzo, puoi anche mappare un comando all'azione di un'estensione. L'esempio seguente inserisce uno script di contenuti che mostra un avviso nella pagina corrente quando l'utente fa clic sull'azione dell'estensione o attiva la scorciatoia da tastiera.

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

Verifica i comandi registrati

Se un'estensione tenta di registrare una scorciatoia già utilizzata da un'altra estensione, la scorciatoia della seconda estensione non verrà registrata come previsto. Puoi offrire un'esperienza utente finale più solida anticipando questa possibilità e verificando la presenza di collisioni al momento dell'installazione.

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

Tipi

Command

Proprietà

  • descrizione

    stringa facoltativa

    La descrizione del comando dell'estensione

  • nome

    stringa facoltativa

    Il nome del comando dell'estensione

  • scorciatoia

    stringa facoltativa

    La scorciatoia attiva per questo comando o vuota se non è attiva.

Metodi

getAll()

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

Restituisce tutti i comandi dell'estensione registrati per questa estensione e la relativa scorciatoia (se attiva). Prima di Chrome 110, questo comando non restituiva _execute_action.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (commands: Command[]) => void

Resi

  • Promise<Command[]>

    Chrome 96 e versioni successive

    Risolve con un elenco dei comandi registrati.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onCommand

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

Attivato quando un comando registrato viene attivato utilizzando una scorciatoia da tastiera.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • comando

      stringa

    • tab

      tabs.Tab facoltativo