Descrizione
Utilizza l'API dei comandi 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
Concetti e utilizzo
L'API Commands consente agli sviluppatori di estensioni di definire comandi specifici e associarli a un valore predefinito
combinazione di tasti. Ogni comando accettato da un'estensione deve essere dichiarato come proprietà
"commands"
nel file manifest dell'estensione.
La chiave della proprietà viene utilizzata come nome del comando. Gli oggetti comando possono avere due proprietà.
suggested_key
Una proprietà facoltativa che dichiara le scorciatoie da tastiera predefinite per il comando. Se omesso, il parametro verrà slegato. Questa proprietà può assumere una stringa o un valore di oggetto.
Un valore stringa specifica la scorciatoia da tastiera predefinita da utilizzare in tutte piattaforme di terze parti.
Un valore oggetto consente allo sviluppatore dell'estensione di personalizzare la scorciatoia da tastiera per ogni completamente gestita. Quando fornisci scorciatoie specifiche per piattaforma, le proprietà degli oggetti valide sono
default
,chromeos
,linux
,mac
ewindows
.
Per ulteriori dettagli, consulta Requisiti per le combinazioni di tasti.
description
Stringa utilizzata per fornire all'utente una breve descrizione dello scopo del comando. Questa stringa viene visualizzato nell'interfaccia utente di gestione delle scorciatoie da tastiera delle estensioni. Le descrizioni sono obbligatorie per i ma vengono ignorati per i comandi di azione.
Un'estensione può avere molti comandi, ma può specificare al massimo quattro scorciatoie da tastiera suggerite. La
L'utente può aggiungere manualmente altre scorciatoie dalla finestra di dialogo chrome://extensions/shortcuts
.
Chiavi supportate
I tasti riportati di seguito sono scorciatoie per i comandi utilizzabili. Le definizioni chiave sono sensibili alle maiuscole. Tentativo di caricare un'estensione con una chiave con lettere maiuscole e minuscole errata comporterà un errore di analisi del file manifest in per l'installazione.
- Tasti alfabetici
A
...Z
- Tasti numerici
0
...9
- Stringhe di chiavi standard
Generali:
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
Tasti freccia:
Up
,Down
,Left
,Right
Tasti multimediali:
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
,MediaStop
- Stringhe di 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
oAlt
.- I modificatori non possono essere utilizzati in combinazione con i tasti multimediali.
In macOS,
Ctrl
viene automaticamente convertito inCommand
.Per usare il tasto Ctrl su macOS, sostituisci
Ctrl
conMacCtrl
quando definisci"mac"
scorciatoia.L'utilizzo 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à Le scorciatoie dei comandi delle estensioni non possono essere sostituite.
Gestire gli eventi dei comandi
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 tuo 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
_execute_action
(manifest V3), _execute_browser_action
(manifest V2) e
I comandi _execute_page_action
(Manifest V2) sono riservati all'azione di attivare l'azione.
rispettivamente l'azione nel browser o l'azione della pagina. Questi comandi non inviano
command.onCommand come i comandi standard.
Se devi intervenire in base all'apertura del popup, considera la possibilità di ascoltare Evento DOMContentLoaded nel codice JavaScript del popup.
Ambito
Per impostazione predefinita, l'ambito dei comandi è limitato al browser Chrome. Ciò significa che quando il browser non lo stato attivo, le scorciatoie dei comandi non sono attive. A partire da Chrome 35, gli sviluppatori di estensioni possono facoltativamente, contrassegna un comando come "globale". I comandi globali funzionano anche quando Chrome non è attivo.
Le scorciatoie da tastiera suggerite per i comandi globali sono limitate a Ctrl+Shift+[0..9]
. Si tratta di un
una misura di protezione per ridurre al minimo il rischio di eseguire l'override delle scorciatoie in altre applicazioni, dato che se, ad esempio,
ad esempio, Alt+P
doveva essere consentito come globale, la scorciatoia da tastiera per aprire una finestra di dialogo di stampa
potrebbero non funzionare in altre applicazioni.
Gli utenti finali sono liberi di rimappare i comandi globali in base alla combinazione di tasti che preferiscono utilizzando l'interfaccia utente esposta
alle ore 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. Al suo più basilare, un comando richiede soltanto una dichiarazione del comando nel manifest dell'estensione e un listener registrazione 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 Concetti e utilizzo, puoi anche mappare un comando allo un'azione. 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 il 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 comandi registrati
Se un'estensione tenta di registrare una scorciatoia già utilizzata da un'altra estensione, la scorciatoia della seconda estensione non viene registrata come previsto. Puoi offrire un utente finale più affidabile un'esperienza ottimale anticipando questa possibilità e verificando la presenza di eventuali 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.
}
});
}
Tipi
Command
Proprietà
-
descrizione
stringa facoltativo
Descrizione del comando estensione
-
nome
stringa facoltativo
Il nome del comando estensione
-
scorciatoia
stringa facoltativo
La scorciatoia è attiva per questo comando oppure lascia il campo vuoto se non è attiva.
Metodi
getAll()
chrome.commands.getAll(
callback?: function,
)
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
Resi
-
Prometti<Comando[]>
Chrome 96 e versioni successive .Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
Eventi
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Attivato quando viene attivato un comando registrato utilizzando una scorciatoia da tastiera.