browser.action

Description

Utilisez l'API chrome.action pour contrôler l'icône de l'extension dans la barre d'outils Google Chrome.

Les icônes d'action s'affichent dans la barre d'outils du navigateur, à côté de l'omnibox. Une fois installées, elles s'affichent dans le menu des extensions (icône en forme de pièce de puzzle). Les utilisateurs peuvent épingler l'icône de votre extension à la barre d'outils.

Disponibilité

Navigateur Chrome 88 ou version ultérieure * depuis Chrome 148 MV3 ou version ultérieure

Fichier manifeste

Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.

"action"

Pour utiliser l'API browser.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. Lorsqu'elle n'est pas incluse, votre extension s'affiche toujours dans la barre d'outils pour permettre d'accéder au menu de l'extension. C'est pourquoi nous vous recommandons de toujours inclure au moins les clés "action" et "default_icon".

Concepts et utilisation

Parties de l'UI

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 l'appareil (DIP) de largeur et de hauteur.

La clé "default_icon" est un dictionnaire de tailles pour les chemins d'accès aux images. Chrome utilise ces icônes pour choisir l'échelle d'image à utiliser. Si aucune correspondance exacte n'est trouvée, Chrome sélectionne la taille disponible 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 de scaling moins courants, tels que 1,5x ou 1,2x, sont de plus en plus courants, nous vous encourageons à fournir plusieurs tailles pour vos icônes. Cela permet également de pérenniser votre extension contre d'éventuelles modifications de la 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'accès à l'image ou en fournissant une icône générée de manière dynamique à l'aide de l'élément canevas HTML ou, si vous la définissez à partir d'un service worker d'extension, de l'API canevas hors écran.

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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

Pour les extensions empaqueté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 non empaquetées doivent utiliser des images PNG.

Info-bulle (titre)

L'info-bulle ou le titre s'affiche lorsque l'utilisateur pointe le pointeur de la souris sur l'icône de l'extension dans la barre d'outils. Il est également inclus dans le texte accessible énoncé 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 de manière programmatique en appelant action.setTitle().

Badge

Les actions peuvent éventuellement afficher un "badge", c'est-à-dire un peu de 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. Comme l'espace est limité, nous vous recommandons d'utiliser quatre caractères ou moins pour le texte du badge.

Pour créer un badge, définissez-le de manière programmatique en appelant action.setBadgeBackgroundColor() et action.setBadgeText(). Aucun paramètre de badge par défaut n'est défini dans le fichier manifeste. Les valeurs de couleur du badge peuvent être un tableau de quatre entiers compris entre 0 et 255 qui constituent la couleur RVBA du badge, ou une chaîne avec une valeur de couleur CSS.

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

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

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

Un pop-up d'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 sera automatiquement redimensionné pour s'adapter à 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" de la clé "action" dans le fichier manifest.json. Si elle est présente, cette propriété doit pointer vers un chemin relatif dans le répertoire de l'extension. Il peut également être mis à jour de manière dynamique pour pointer vers un autre chemin relatif à l'aide de la méthode action.setPopup().

Cas d'utilisation

État par onglet

Les actions d'extension peuvent avoir des états différents 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() { /* ... */}

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

Si la propriété tabId est omise, le paramètre est traité comme un paramètre global. Les paramètres spécifiques à un onglet sont prioritaires sur les paramètres généraux.

État d'activation

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'affecte que l'envoi du pop-up (le cas échéant) ou de l'événement action.onClicked à votre extension. Cela n'affecte pas la présence de l'action dans la barre d'outils.

Exemples

Les exemples suivants montrent quelques-unes des façons dont les actions sont utilisées dans les extensions. Pour essayer cette API, installez l'exemple d'API Action à 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 lors d'un 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
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

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

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

Types

OpenPopupOptions

Chrome 99+ browser.* depuis Chrome 148

Propriétés

  • windowId

    number facultatif

    ID de la fenêtre dans laquelle ouvrir le pop-up d'action. Si aucune valeur n'est spécifiée, la valeur par défaut est la fenêtre actuellement active.

TabDetails

Propriétés

  • tabId

    number facultatif

    ID de l'onglet dont l'état doit être interrogé. Si aucun onglet n'est spécifié, l'état non spécifique à un onglet est renvoyé.

UserSettings

Chrome 91 et versions ultérieures browser.* depuis Chrome 148

Ensemble de paramètres spécifiés par l'utilisateur et liés à l'action d'une extension.

Propriétés

  • isOnToolbar

    booléen

    Indique si l'icône d'action de l'extension est visible dans la barre d'outils de niveau supérieur des fenêtres du navigateur (c'est-à-dire si l'extension a été "épinglée" par l'utilisateur).

UserSettingsChange

Chrome 130+ browser.* depuis Chrome 148

Propriétés

  • isOnToolbar

    boolean facultatif

    Indique si l'icône d'action de l'extension est visible dans la barre d'outils de niveau supérieur des fenêtres du navigateur (c'est-à-dire si l'extension a été "épinglée" par l'utilisateur).

Méthodes

disable()

browser.action.disable(
  tabId?: number,
): Promise<void>

Désactive l'action pour un onglet.

Paramètres

  • tabId

    number facultatif

    ID de l'onglet pour lequel vous souhaitez modifier l'action.

Renvoie

  • Promise<void>

enable()

browser.action.enable(
  tabId?: number,
): Promise<void>

Active l'action pour un onglet. Par défaut, les actions sont activées.

Paramètres

  • tabId

    number facultatif

    ID de l'onglet pour lequel vous souhaitez modifier l'action.

Renvoie

  • Promise<void>

getBadgeBackgroundColor()

browser.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

Récupère la couleur d'arrière-plan de l'action.

Paramètres

Renvoie

getBadgeText()

browser.action.getBadgeText(
  details: TabDetails,
): Promise<string>

Récupère le texte du badge de l'action. Si aucun onglet n'est spécifié, le texte du badge non spécifique à un onglet est renvoyé. Si displayActionCountAsBadgeText est activé, un texte d'espace réservé est renvoyé, sauf si l'autorisation declarativeNetRequestFeedback est présente ou si un texte de badge spécifique à l'onglet a été fourni.

Paramètres

Renvoie

  • Promise<string>

getBadgeTextColor()

Navigateur Chrome 110+ * depuis Chrome 148 
browser.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

Récupère la couleur du texte de l'action.

Paramètres

Renvoie

getPopup()

browser.action.getPopup(
  details: TabDetails,
): Promise<string>

Récupère le document HTML défini comme pop-up pour cette action.

Paramètres

Renvoie

  • Promise<string>

getTitle()

browser.action.getTitle(
  details: TabDetails,
): Promise<string>

Récupère le titre de l'action.

Paramètres

Renvoie

  • Promise<string>

getUserSettings()

Chrome 91 et versions ultérieures browser.* depuis Chrome 148 
browser.action.getUserSettings(): Promise<UserSettings>

Renvoie les paramètres spécifiés par l'utilisateur concernant l'action d'une extension.

Renvoie

isEnabled()

Navigateur Chrome 110+ * depuis Chrome 148 
browser.action.isEnabled(
  tabId?: number,
): Promise<boolean>

Indique si l'action de l'extension est activée pour un onglet (ou de manière globale si aucun tabId n'est fourni). Les actions activées à l'aide de declarativeContent uniquement renvoient toujours la valeur "false".

Paramètres

  • tabId

    number facultatif

    ID de l'onglet dont vous souhaitez vérifier l'état d'activation.

Renvoie

  • Promise<boolean>

openPopup()

Chrome 127+ browser.* depuis Chrome 148 
browser.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

Ouvre le pop-up de l'extension. Entre Chrome 118 et Chrome 126, cette fonctionnalité n'est disponible que pour les extensions installées par des règles.

Paramètres

  • options

    OpenPopupOptions facultatif

    Spécifie les options d'ouverture du pop-up.

Renvoie

  • Promise<void>

setBadgeBackgroundColor()

browser.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

Définit la couleur d'arrière-plan du badge.

Paramètres

  • détails

    objet

    • couleur

      string | ColorArray

      Tableau de quatre entiers compris entre 0 et 255 qui constituent la couleur RVBA du badge. Par exemple, le rouge opaque est [255, 0, 0, 255]. Il peut également s'agir d'une chaîne avec une valeur CSS, le rouge opaque étant #FF0000 ou #F00.

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

Renvoie

  • Promise<void>

setBadgeText()

browser.action.setBadgeText(
  details: object,
): Promise<void>

Définit le texte du badge pour l'action. Le badge s'affiche au-dessus de l'icône.

Paramètres

  • détails

    objet

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

    • texte

      chaîne facultatif

      Vous pouvez transmettre n'importe quel nombre de caractères, mais seuls quatre d'entre eux peuvent tenir dans l'espace. Si une chaîne vide ('') est transmise, le texte du badge est effacé. Si tabId est spécifié et que text est nul, le texte de l'onglet spécifié est effacé et remplacé par le texte du badge global par défaut.

Renvoie

  • Promise<void>

setBadgeTextColor()

Navigateur Chrome 110+ * depuis Chrome 148 
browser.action.setBadgeTextColor(
  details: object,
): Promise<void>

Définit la couleur du texte du badge.

Paramètres

  • détails

    objet

    • couleur

      string | ColorArray

      Tableau de quatre entiers compris entre 0 et 255 qui constituent la couleur RVBA du badge. Par exemple, le rouge opaque est [255, 0, 0, 255]. Il peut également s'agir d'une chaîne avec une valeur CSS, le rouge opaque étant #FF0000 ou #F00. Si vous ne définissez pas cette valeur, une couleur sera automatiquement choisie pour contraster avec la couleur d'arrière-plan du badge afin que le texte soit visible. Les couleurs dont la valeur alpha est égale à 0 ne seront pas définies et renverront une erreur.

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

Renvoie

  • Promise<void>

setIcon()

browser.action.setIcon(
  details: object,
): Promise<void>

Définit l'icône de l'action. L'icône peut être spécifiée soit comme le chemin d'accès à un fichier image, soit comme les données de pixels d'un élément canevas, soit comme un dictionnaire de l'un ou l'autre. Vous devez spécifier la propriété path ou imageData.

Paramètres

  • détails

    objet

    • imageData

      ImageData | objet facultatif

      Objet ImageData ou dictionnaire {size -> ImageData} représentant l'icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image réelle à utiliser est choisie en fonction de la densité de pixels de l'écran. Si le nombre de pixels d'image qui tiennent dans une unité d'espace d'écran est égal à scale, l'image de taille scale * n sera sélectionnée, où n est la taille de l'icône dans l'interface utilisateur. Vous devez spécifier au moins une image. Notez que "details.imageData = foo" équivaut à "details.imageData = {'16': foo}".

    • chemin d'accès

      string | object facultatif

      Chemin d'accès relatif à l'image ou dictionnaire {size -> relative image path} pointant vers l'icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image réelle à utiliser est choisie en fonction de la densité de pixels de l'écran. Si le nombre de pixels d'image qui tiennent dans une unité d'espace d'écran est égal à scale, l'image de taille scale * n sera sélectionnée, où n est la taille de l'icône dans l'interface utilisateur. Vous devez spécifier au moins une image. Notez que "details.path = foo" équivaut à "details.path = {'16': foo}".

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

Renvoie

  • Promise<void>

    Chrome 96+ browser.* depuis Chrome 148

setPopup()

browser.action.setPopup(
  details: object,
): Promise<void>

Définit le document HTML à ouvrir en tant que pop-up lorsque l'utilisateur clique sur l'icône de l'action.

Paramètres

  • détails

    objet

    • pop-up

      chaîne

      Chemin relatif au fichier HTML à afficher dans un pop-up. Si elle est définie sur une chaîne vide (''), aucun pop-up ne s'affiche.

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

Renvoie

  • Promise<void>

setTitle()

browser.action.setTitle(
  details: object,
): Promise<void>

Définit le titre de l'action. Il s'affiche dans l'info-bulle.

Paramètres

  • détails

    objet

    • tabId

      number facultatif

      Limite la modification à la sélection d'un onglet particulier. Se réinitialise automatiquement lorsque l'onglet est fermé.

    • titre

      chaîne

      Chaîne que l'action doit afficher lorsque l'utilisateur pointe dessus.

Renvoie

  • Promise<void>

Événements

onClicked

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

Déclenché lorsqu'un utilisateur clique sur une icône d'action. Cet événement ne se déclenche pas si l'action comporte un pop-up.

Paramètres

  • callback

    fonction

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

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130+ browser.* depuis Chrome 148 
browser.action.onUserSettingsChanged.addListener(
  callback: function,
)

Se déclenche lorsque les paramètres spécifiés par l'utilisateur concernant l'action d'une extension changent.

Paramètres