chrome.commands

Descrizione

Manifest

Concetti e utilizzo

L'API Commands consente agli sviluppatori di estensioni di definire comandi specifici e di associarli a una combinazione di chiavi 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 assumere 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ò utilizzare una 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 Requisiti per le combinazioni di chiavi.

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 delle estensioni. 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

Le seguenti chiavi sono scorciatoie dei comandi utilizzabili. Le definizioni chiave sono sensibili alle maiuscole. Il tentativo di caricare un'estensione con una chiave scritta in modo non corretto comporterà un errore di analisi del file manifest al momento dell'installazione.

Chiavi alfabetiche

A... Z

Tasti numerici

0... 9

Stringhe di chiave 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.

• In macOS, Ctrl viene convertito automaticamente in Command.

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

  • L'uso di MacCtrl in 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 esempio la gestione delle finestre) hanno sempre la priorità sulle scorciatoie dei comandi delle estensioni e non possono essere sovrascritte.

Gestire gli 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'azione di attivare l'azione, l'azione del browser o l'azione sulla pagina. Questi comandi non inviano eventi command.onCommand come i comandi standard.

Se devi intervenire in base all'apertura del popup, potresti ascoltare un evento DOMContentLoaded all'interno del codice JavaScript del popup.

Ambito

Per impostazione predefinita, l'ambito dei comandi è il browser Chrome. Ciò significa che quando il browser non è attivo, le scorciatoie dei comandi sono inattive. A partire dalla versione 35 di Chrome, gli sviluppatori di estensioni possono contrassegnare un comando come "globale". Anche i comandi globali funzionano quando Chrome non è impostato sullo stato attivo.

I suggerimenti delle scorciatoie da tastiera per i comandi globali sono limitati a Ctrl+Shift+[0..9]. Questa è una misura di protezione per ridurre al minimo il rischio di eseguire l'override delle scorciatoie in altre applicazioni poiché, ad esempio, se Alt+P dovesse essere 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 loro combinazione di tasti preferita utilizzando l'UI esposta in 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. In ultima analisi, un comando richiede solo una dichiarazione del comando nel manifest dell'estensione e una registrazione del 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, quella della seconda estensione non verrà registrata come previsto. Puoi fornire un'esperienza più solida per l'utente finale prevedendo questa eventualità e verificando la presenza di collisioni al momento dell'installazione.

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(
  callback?: function,
)

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