chrome.commands

Description

Fichier manifeste

Concepts et utilisation

L'API Commands permet aux développeurs d'extensions de définir des commandes spécifiques et de les associer à une combinaison de touches par défaut. Chaque commande acceptée par une extension doit être déclarée comme 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 prendre deux propriétés.

suggested_key

Propriété facultative qui déclare les raccourcis clavier par défaut pour la commande. Si elle est omise, la commande ne sera pas associée. Cette propriété peut prendre une valeur de chaîne ou 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'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 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 s'affiche 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 comporter de nombreuses commandes, mais ne peut spécifier qu'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 acceptées

Les touches suivantes peuvent être utilisées comme raccourcis de commande. 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 lors 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

Touches multimédias : MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Chaînes de touches de modification

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

Exigences relatives aux combinaisons de touches

• Les raccourcis de commande d'extension doivent inclure Ctrl ou Alt.

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

  • Sur de nombreux claviers macOS, Alt fait référence à la touche Option.

  • Sur macOS, Command ou MacCtrl peuvent également être utilisés à la place de Ctrl ou Alt (voir le point suivant).

• Sur macOS, Ctrl est automatiquement converti en Command.

  • Command peut également être utilisé dans le raccourci "mac" pour faire explicitement référence à la touche de commande.

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

  • Si vous utilisez MacCtrl dans la combinaison pour une autre plate-forme, une erreur de validation se produira et l'extension ne pourra pas être installée.

• 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 par rapport aux raccourcis de commandes d'extension et ne peuvent pas être ignoré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 associer 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, de l'action du navigateur ou de l'action de la page, respectivement. Ces commandes n'envoient pas d'événements command.onCommand comme les commandes standards.

Si vous devez effectuer une action en fonction de l'ouverture de votre pop-up, envisagez d'écouter un événement DOMContentLoaded dans le code JavaScript de votre 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 au premier plan, les raccourcis clavier sont inactifs. À partir de Chrome 35, les développeurs d'extensions peuvent éventuellement marquer une commande comme "globale". Les commandes globales fonctionnent également lorsque Chrome n'est pas au premier plan.

Les suggestions de raccourcis clavier pour les commandes globales sont limitées à Ctrl+Shift+[0..9]. Il s'agit d'une mesure de protection visant à minimiser le risque de remplacement des raccourcis dans d'autres applications. En effet, si, par exemple, Alt+P était autorisé en tant que raccourci global, 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 sur la combinaison de touches de leur choix à l'aide de l'UI exposé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

Les exemples suivants illustrent les fonctionnalités de base de l'API Commands.

Commande de base

Les commandes permettent aux extensions de mapper la logique à des raccourcis clavier que l'utilisateur peut appeler. 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 Concepts et 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 s'enregistre pas comme prévu. Vous pouvez offrir une expérience utilisateur plus robuste en anticipant cette possibilité et en vérifiant 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.
    }
  });
}

chrome.commands.getAll(): Promise<Command[]>

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