chrome.commands

Description

Utilisez l'API de commandes pour ajouter des raccourcis clavier qui déclenchent des actions dans votre extension (par exemple, une action permettant d'ouvrir l'action du navigateur ou d'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 de commande 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 utiliser 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 de l'extension 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 et windows.

Pour en savoir plus, consultez les exigences concernant les combinaisons de clés.

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'interface utilisateur de gestion des raccourcis clavier des extensions. Les descriptions sont obligatoires pour les commandes standards, mais sont ignorées pour les commandes d'action.

Une extension peut contenir de nombreuses commandes, mais peut spécifier au maximum quatre raccourcis clavier suggérés. 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 commande utilisables. Les définitions de clé sont sensibles à la casse. Toute tentative de chargement d'une extension avec une clé dont la casse est incorrecte entraînera une erreur d'analyse du fichier manifeste au moment de l'installation.

Clés 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

Clés multimédias : MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Chaînes de touches de modification

Ctrl, Alt (Option sous macOS), Shift, MacCtrl (macOS uniquement), Command (macOS uniquement), Search (ChromeOS uniquement)

Exigences concernant les combinaisons de clés

  • Les raccourcis de commandes de l'extension doivent inclure Ctrl ou Alt.

    • Les modificateurs ne peuvent pas être utilisés avec des touches multimédias.

  • Sous macOS, Ctrl est automatiquement converti en Command.

    • Pour utiliser la touche Ctrl sous macOS, remplacez Ctrl par MacCtrl lorsque vous définissez le raccourci "mac".

    • Si vous utilisez MacCtrl en combinaison avec une autre plate-forme, cela entraînera une erreur de validation et empêchera l'installation de l'extension.

  • Shift est un modificateur facultatif sur toutes les plates-formes.

  • Search est un modificateur facultatif exclusif à 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 écrasé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 respectivement réservées à l’action de déclenchement d'une action, d'une action de navigateur ou d'une action sur la page. Ces commandes ne envoient pas d'événements command.onCommand comme les commandes standards.

Si vous devez intervenir en fonction de l'ouverture de votre pop-up, pensez à écouter un événement DOMContentLoaded dans le code JavaScript de votre pop-up.

Définition du champ d'application

Par défaut, les commandes s'appliquent au navigateur Chrome. Cela signifie que lorsque le navigateur n'est pas sélectionné, les raccourcis de commandes 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 lorsque Chrome n'est pas sélectionné.

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 était autorisé comme étant global, le raccourci clavier permettant d'ouvrir une boîte de dialogue d'impression risque de ne pas fonctionner dans d'autres applications.

Les utilisateurs finaux sont libres de remapper les commandes globales avec leur combinaison de touches préférée à l'aide de l'interface utilisateur présentée à l'adresse 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

Dans les exemples suivants, les fonctionnalités de base de l'API Commands sont flexibles.

Commande de base

Les commandes permettent aux extensions de mapper la logique aux 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 les commandes enregistrées

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 collisions 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

    string facultatif

    Description de la commande Extension

  • name

    string facultatif

    Le nom de la commande Extension

  • raccourci

    string facultatif

    Raccourci actif pour cette commande ou vide s'il n'est pas actif.

Méthodes

getAll()

Promesse 
chrome.commands.getAll(
  callback?: function,
)

Renvoie toutes les commandes d'extension enregistrées pour cette extension et leur raccourci (s'il est actif). Avant Chrome 110, cette commande ne renvoyait pas _execute_action.

Paramètres

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    (commands: Command[])=>void

Renvoie

  • Promettre<Commande[]>

    Chrome 96 et versions ultérieures

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans 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.

Paramètres

  • rappel

    function

    Le paramètre callback se présente comme suit : 

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

    • commande

      chaîne

    • tab

      tabs.Tab facultatif