chrome.action

Description

Disponibilité

Fichier manifeste

Pour utiliser l'API chrome.action, spécifiez un "manifest_version" de 3 et incluez la clé "action" dans votre fichier manifeste.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

La clé "action" (ainsi que ses enfants) est facultative. Si elle n'est pas incluse, votre extension s'affiche toujours dans la barre d'outils pour permettre d'accéder à son menu. C'est pourquoi nous vous recommandons d'inclure au moins les clés "action" et "default_icon".

Concepts et utilisation

Éléments de l'interface utilisateur

Icône

L'icône est l'image principale de la barre d'outils de votre extension. Elle est définie par la clé "default_icon" dans la clé "action" de votre fichier manifeste. Les icônes doivent mesurer 16 pixels indépendants de la densité (DIP) de large et de haut.

La clé "default_icon" est un dictionnaire des tailles et des chemins d'accès aux images. Chrome utilise ces icônes pour choisir l'échelle d'image à utiliser. En l'absence de correspondance exacte, Chrome sélectionne la taille la plus proche et l'adapte à l'image, ce qui peut affecter la qualité de l'image.

Étant donné que les appareils avec des facteurs d'échelle moins courants, comme 1,5x ou 1,2x, sont de plus en plus répandus, nous vous encourageons à fournir plusieurs tailles pour vos icônes. Cela permet également de pérenniser votre extension face à d'éventuels changements de taille d'affichage des icônes. Toutefois, si vous ne fournissez qu'une seule taille, la clé "default_icon" peut également être définie sur une chaîne avec le chemin d'accès à une seule icône au lieu d'un dictionnaire.

Vous pouvez également appeler action.setIcon() pour définir l'icône de votre extension de manière programmatique en spécifiant un autre chemin d'image ou en fournissant une icône générée dynamiquement à l'aide de l'élément canvas HTML ou, si vous la définissez à partir d'un service worker d'extension, de l'API offscreen canvas.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

Pour les extensions compressées (installées à partir d'un fichier .crx), les images peuvent être dans la plupart des formats que le moteur de rendu Blink peut afficher, y compris PNG, JPEG, BMP, ICO, etc. Le format SVG n'est pas accepté. Les extensions décompressées doivent utiliser des images PNG.

Info-bulle (titre)

L'info-bulle ou le titre s'affichent lorsque l'utilisateur pointe sur l'icône de l'extension dans la barre d'outils. Il est également inclus dans le texte accessible lu par les lecteurs d'écran lorsque le bouton est sélectionné.

L'info-bulle par défaut est définie à l'aide du champ "default_title" de la clé "action" dans manifest.json. Vous pouvez également le définir par programmation en appelant action.setTitle().

Badge

Les actions peuvent éventuellement afficher un "badge", c'est-à-dire un petit texte superposé à l'icône. Cela vous permet de mettre à jour l'action pour afficher une petite quantité d'informations sur l'état de l'extension, comme un compteur. Le badge comporte un composant de texte et une couleur d'arrière-plan. L'espace étant limité, nous vous recommandons d'utiliser quatre caractères ou moins pour le texte du badge.

Pour créer un badge, définissez-le par programmation en appelant action.setBadgeBackgroundColor() et action.setBadgeText(). Il n'existe pas de paramètre de badge par défaut dans le fichier manifeste. Les valeurs de couleur des badges peuvent être un tableau de quatre entiers compris entre 0 et 255 qui composent la couleur RVBA du badge, ou une chaîne avec une valeur de couleur CSS.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Fenêtre pop-up

Le pop-up d'une action s'affiche lorsque l'utilisateur clique sur le bouton d'action de l'extension dans la barre d'outils. Le pop-up peut contenir n'importe quel contenu HTML et sa taille sera automatiquement ajustée à son contenu. La taille du pop-up doit être comprise entre 25 x 25 et 800 x 600 pixels.

Le pop-up est initialement défini par la propriété "default_popup" dans la clé "action" du fichier manifest.json. Si elle est présente, cette propriété doit pointer vers un chemin d'accès relatif dans le répertoire de l'extension. Il peut également être mis à jour de manière dynamique pour pointer vers un autre chemin d'accès relatif à l'aide de la méthode action.setPopup().

Cas d'utilisation

État par onglet

Les actions d'extension peuvent avoir différents états pour chaque onglet. Pour définir une valeur pour un onglet individuel, utilisez la propriété tabId dans les méthodes de paramètre de l'API action. Par exemple, pour définir le texte du badge d'un onglet spécifique, procédez comme suit :

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Si la propriété tabId est omise, le paramètre est considéré comme global. Les paramètres spécifiques à un onglet sont prioritaires par rapport aux paramètres généraux.

État activé

Par défaut, les actions de la barre d'outils sont activées (cliquables) dans chaque onglet. Vous pouvez modifier cette valeur par défaut en définissant la propriété default_state dans la clé action du fichier manifeste. Si default_state est défini sur "disabled", l'action est désactivée par défaut et doit être activée de manière programmatique pour être cliquable. Si default_state est défini sur "enabled" (valeur par défaut), l'action est activée et cliquable par défaut.

Vous pouvez contrôler l'état de manière programmatique à l'aide des méthodes action.enable() et action.disable(). Cela n'a d'incidence que sur l'envoi ou non du pop-up (le cas échéant) ou de l'événement action.onClicked à votre extension. Cela n'a aucune incidence sur la présence de l'action dans la barre d'outils.

Exemples

Les exemples suivants illustrent certaines utilisations courantes des actions dans les extensions. Pour essayer cette API, installez l'exemple d'API Actions à partir du dépôt chrome-extension-samples.

Afficher un pop-up

Il est courant qu'une extension affiche un pop-up lorsque l'utilisateur clique sur l'action de l'extension. Pour implémenter cela dans votre propre extension, déclarez le pop-up dans votre manifest.json et spécifiez le contenu que Chrome doit afficher dans le pop-up.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

Injecter un script de contenu au clic

Un modèle courant pour les extensions consiste à exposer leur fonctionnalité principale à l'aide de l'action de l'extension. L'exemple suivant illustre ce modèle. Lorsque l'utilisateur clique sur l'action, l'extension injecte un script de contenu dans la page actuelle. Le script de contenu affiche ensuite une alerte pour vérifier que tout a fonctionné comme prévu.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

Émuler des actions avec declarativeContent

Cet exemple montre comment la logique d'arrière-plan d'une extension peut (a) désactiver une action par défaut et (b) utiliser declarativeContent pour activer l'action sur des sites spécifiques.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

chrome.action.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.action.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.action.getUserSettings(
  callback?: function,
): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.setIcon(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.setPopup(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.setTitle(
  details: object,
  callback?: function,
): Promise<void>

chrome.action.onClicked.addListener(
  callback: function,
)

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)