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 lier à un combinaison de touches. Chaque commande acceptée par une extension doit être déclarée en tant que propriété de "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. En cas d'omission, 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 plates-formes.

• Une valeur d'objet permet au développeur de l'extension de personnaliser le raccourci clavier pour chaque Google Cloud. 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 apparaît dans l'UI de gestion des raccourcis clavier de l'extension. Les descriptions sont obligatoires pour les , 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. La l'utilisateur peut ajouter manuellement d'autres raccourcis depuis 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. Tentative de le chargement d'une extension avec une clé mal placée entraînera une erreur d'analyse du fichier manifeste à le temps d'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) et Search (ChromeOS uniquement)

Exigences concernant les combinaisons de clés

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

  • Les modificateurs ne peuvent pas être utilisés en combinaison 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 "mac". raccourci.

  • 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 systèmes d'exploitation et raccourcis Chrome (par exemple, la gestion des fenêtres) sont toujours prioritaires sur les raccourcis des commandes de l'extension. Ils 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. avec onCommand.addListener. Exemple :

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Commandes d'action

_execute_action (Manifest V3), _execute_browser_action (Manifest V2) et Les commandes _execute_page_action (Manifest V2) sont réservées au déclenchement de votre action, l'action du navigateur ou l'action sur la page, respectivement. Ces commandes ne transmettent pas command.onCommand comme les commandes standards.

Si vous devez agir en fonction de l'ouverture de votre pop-up, pensez à écouter un 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 sont actifs, les raccourcis de commande sont inactifs. À partir de Chrome 35, les développeurs d'extensions vous pouvez éventuellement marquer une commande comme "global". 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'un mesure de protection visant à réduire le risque d'ignorer les raccourcis dans d'autres applications, car si, pour Exemple : Alt+P doit être autorisé comme global, le raccourci clavier permettant d'ouvrir une boîte de dialogue d'impression peuvent ne pas fonctionner dans d'autres applications.

Les utilisateurs finaux sont libres de remapper les commandes globales à leur combinaison de touches préférée à l'aide de l'interface utilisateur exposée à 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. À sa la plus basique : une commande ne nécessite qu'une déclaration de commande dans le fichier manifeste de l'extension et un écouteur l'enregistrement, 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 au action. L'exemple suivant injecte un script de contenu qui affiche une alerte qui s'affiche sur la page actuelle lorsque l'utilisateur clique sur l'action de l'extension ou déclenche la 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, la le raccourci de la deuxième extension ne sera pas enregistré comme prévu. Vous pouvez fournir à l'utilisateur final en anticipant cette possibilité et en vérifiant s'il y a des 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(
  callback?: function,
)

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