Description
Utilisez l'API des commandes pour ajouter des raccourcis clavier qui déclenchent des actions dans votre extension, par exemple une action pour ouvrir l'action du navigateur ou envoyer une commande à l'extension.
Manifest
Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.
"commands"
Concepts et utilisation
L'API Commands permet aux développeurs d'extensions de définir des commandes spécifiques et de les lier à une combinaison de touches par défaut. Chaque commande acceptée par une extension doit être déclarée en tant que propriété de l'objet "commands"
dans le fichier manifeste de l'extension.
La clé de propriété est utilisée comme nom de la commande. Les objets Command peuvent avoir deux propriétés.
suggested_key
Propriété facultative qui déclare les raccourcis clavier par défaut pour la commande. Si cette valeur est omise, la commande est dissociée. Cette propriété peut accepter une chaîne ou une valeur d'objet.
Une valeur de chaîne spécifie le raccourci clavier par défaut à utiliser sur toutes les plates-formes.
Une valeur d'objet permet au développeur d'extensions de personnaliser le raccourci clavier pour chaque plate-forme. Lorsque vous fournissez des raccourcis spécifiques à une plate-forme, les propriétés d'objet valides sont
default
,chromeos
,linux
,mac
etwindows
.
Pour en savoir plus, consultez Exigences concernant les combinaisons de touches.
description
Chaîne utilisée pour fournir à l'utilisateur une brève description de l'objectif de la commande. Cette chaîne apparaît dans l'UI de gestion des raccourcis clavier de l'extension. Les descriptions sont obligatoires pour les commandes standards, mais sont ignorées pour les commandes d'action.
Une extension peut comporter de nombreuses commandes, mais peut comporter jusqu'à quatre suggestions de raccourcis clavier. L'utilisateur peut ajouter manuellement d'autres raccourcis à partir de la boîte de dialogue chrome://extensions/shortcuts
.
Clés compatibles
Les touches suivantes sont des raccourcis de commandes utilisables. Les définitions clés sont sensibles à la casse. Toute tentative de chargement d'une extension avec une clé mal positionnée entraînera une erreur d'analyse du fichier manifeste au moment de l'installation.
- Touches alpha
A
...Z
- Touches numériques
0
...9
- Chaînes de clés standards
Général :
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
Touches fléchées :
Up
,Down
,Left
,Right
Touches multimédias :
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
,MediaStop
- Chaînes de touches de modification
Ctrl
,Alt
(Option
sous macOS),Shift
,MacCtrl
(macOS uniquement),Command
(macOS uniquement) etSearch
(ChromeOS uniquement)
Exigences concernant les combinaisons de clés
Les raccourcis des commandes de l'extension doivent inclure
Ctrl
ouAlt
.- Les modificateurs ne peuvent pas être utilisés en combinaison avec des touches multimédias.
Sous macOS,
Ctrl
est automatiquement converti enCommand
.Pour utiliser la touche Ctrl sous macOS, remplacez
Ctrl
parMacCtrl
lorsque vous définissez le raccourci"mac"
.Si vous utilisez
MacCtrl
en combinaison avec une autre plate-forme, une erreur de validation se produit et l'extension ne peut pas être installée.
Shift
est un modificateur facultatif sur toutes les plates-formes.Search
est un modificateur facultatif propre à ChromeOS.Certains raccourcis du système d'exploitation et de Chrome (par exemple, la gestion des fenêtres) sont toujours prioritaires sur les raccourcis de commande des extensions et ne peuvent pas être remplacés.
Gérer les événements de commande
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"
}
}
},
...
}
Dans votre service worker, vous pouvez lier un gestionnaire à chacune des commandes définies dans le fichier manifeste à l'aide de onCommand.addListener
. Exemple :
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
Commandes d'action
Les commandes _execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) et _execute_page_action
(Manifest V2) sont réservées à l'action de déclenchement de votre action, celle du navigateur ou de la page, respectivement. Ces commandes n'envoient pas d'événements command.onCommand comme les commandes standards.
Si vous devez prendre des mesures en fonction de l'ouverture de votre pop-up, envisagez d'écouter un événement DOMContentLoaded dans le code JavaScript de la fenêtre pop-up.
Champ d'application
Par défaut, les commandes sont limitées au navigateur Chrome. Cela signifie que lorsque le navigateur n'est pas sélectionné, les raccourcis de commande sont inactifs. À partir de Chrome 35, les développeurs d'extensions peuvent éventuellement marquer une commande comme "globale". Les commandes générales fonctionnent également, mais Chrome n'est pas actif.
Les suggestions de raccourcis clavier pour les commandes générales sont limitées à Ctrl+Shift+[0..9]
. Il s'agit d'une mesure de protection visant à minimiser le risque de remplacer les raccourcis dans d'autres applications. En effet, si, par exemple, Alt+P
devait être autorisé comme général, le raccourci clavier permettant d'ouvrir une boîte de dialogue d'impression pourrait ne pas fonctionner dans d'autres applications.
Les utilisateurs finaux sont libres de remapper les commandes globales à la combinaison de touches de leur choix à l'aide de l'interface utilisateur exposée dans chrome://extensions/shortcuts
.
Exemple :
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
Exemples
Les exemples suivants intègrent les fonctionnalités de base de l'API Commands.
Commande de base
Les commandes permettent aux extensions de mapper la logique sur des raccourcis clavier pouvant être appelés par l'utilisateur. Dans sa forme la plus élémentaire, une commande ne nécessite qu'une déclaration de commande dans le fichier manifeste de l'extension et un enregistrement d'écouteur, comme illustré dans l'exemple suivant.
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`);
});
Commande d'action
Comme décrit dans la section Utilisation, vous pouvez également mapper une commande à l'action d'une extension. L'exemple suivant injecte un script de contenu qui affiche une alerte sur la page actuelle lorsque l'utilisateur clique sur l'action de l'extension ou déclenche le raccourci clavier.
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`);
});
Vérifier l'enregistrement des commandes
Si une extension tente d'enregistrer un raccourci déjà utilisé par une autre extension, le raccourci de la deuxième extension ne sera pas enregistré comme prévu. Vous pouvez offrir une expérience utilisateur plus robuste en anticipant cette possibilité et en recherchant les conflits au moment de l'installation.
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.
}
});
}
Types
Command
Propriétés
-
description
chaîne facultatif
Description de la commande d'extension
-
name
chaîne facultatif
Nom de la commande d'extension
-
raccourci
chaîne facultatif
Raccourci actif pour cette commande, ou vide si ce dernier n'est pas actif.
Méthodes
getAll()
chrome.commands.getAll(
callback?: function,
)
Renvoie toutes les commandes d'extension enregistrées pour cette extension, ainsi que leur raccourci (le cas échéant). Avant Chrome 110, cette commande ne renvoyait pas _execute_action
.
Paramètres
Renvoie
-
Promise<Commande[]>
Chrome 96 ou version ultérieureLes promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Déclenché lorsqu'une commande enregistrée est activée à l'aide d'un raccourci clavier.