chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Description

Utilisez les actions du navigateur pour placer des icônes dans la barre d'outils principale de Google Chrome, à droite de la barre d'adresse. En plus de son icône, une action de navigateur peut comporter une info-bulle, un badge et un pop-up.

Disponibilité

≤ MV2

Dans la figure suivante, le carré multicolore à droite de la barre d'adresse est l'icône d'une action de navigateur. Un pop-up se trouve sous l'icône.

Si vous souhaitez créer une icône qui n'est pas toujours active, utilisez une action sur la page au lieu d'une action du navigateur.

Fichier manifeste

Enregistrez l'action de votre navigateur dans le fichier manifeste de l'extension comme suit :

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Vous pouvez fournir une icône de n'importe quelle taille à utiliser dans Chrome. Chrome sélectionnera l'icône la plus proche et la redimensionnera à la taille appropriée pour remplir l'espace de 16 dip. Toutefois, si la taille exacte n'est pas fournie, cette mise à l'échelle peut entraîner une perte de détails ou un aspect flou de l'icône.

Étant donné que les appareils dotés de 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 garantit également que si la taille d'affichage de l'icône est modifiée, vous n'avez pas besoin de fournir d'autres icônes.

L'ancienne syntaxe permettant d'enregistrer l'icône par défaut est toujours acceptée :

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Parties de l'UI

Une action de navigateur peut comporter une icône, une info-bulle, un badge et un pop-up.

Icône

Les icônes d'action du navigateur dans Chrome mesurent 16 dips (pixels indépendants de l'appareil) de largeur et de hauteur. Les icônes plus grandes sont redimensionnées pour s'adapter, mais pour de meilleurs résultats, utilisez une icône carrée de 16 dip.

Vous pouvez définir l'icône de deux manières : en utilisant une image statique ou l'élément canvas HTML5. L'utilisation d'images statiques est plus simple pour les applications simples, mais vous pouvez créer des interfaces utilisateur plus dynamiques (comme une animation fluide) à l'aide de l'élément canevas.

Les images statiques peuvent être dans n'importe quel format que WebKit peut afficher, y compris BMP, GIF, ICO, JPEG ou PNG. Pour les extensions non empaquetées, les images doivent être au format PNG.

Pour définir l'icône, utilisez le champ default_icon de browser_action dans le fichier manifeste ou appelez la méthode browserAction.setIcon.

Pour afficher correctement l'icône lorsque la densité de pixels de l'écran (ratio size_in_pixel / size_in_dip) est différente de 1, l'icône peut être définie comme un ensemble d'images de différentes tailles. L'image réelle à afficher sera sélectionnée dans l'ensemble pour correspondre au mieux à la taille de pixel de 16 dip. L'ensemble d'icônes peut contenir des spécifications d'icônes de n'importe quelle taille, et Chrome sélectionnera la plus appropriée.

Info-bulle

Pour définir l'info-bulle, utilisez le champ default_title de browser_action dans le fichier manifeste ou appelez la méthode browserAction.setTitle. Vous pouvez spécifier des chaînes spécifiques aux paramètres régionaux pour le champ default_title. Pour en savoir plus, consultez Internationalisation.

Badge

Les actions de navigateur peuvent éventuellement afficher un badge, c'est-à-dire un texte superposé à l'icône. Les badges permettent de mettre à jour facilement l'action du navigateur pour afficher une petite quantité d'informations sur l'état de l'extension.

Comme l'espace est limité, le badge ne doit pas comporter plus de quatre caractères.

Définissez le texte et la couleur du badge à l'aide de browserAction.setBadgeText et browserAction.setBadgeBackgroundColor, respectivement.

Si une action de navigateur comporte un pop-up, celui-ci s'affiche lorsque l'utilisateur clique sur l'icône de l'extension. Le pop-up peut contenir n'importe quel contenu HTML et sa taille est automatiquement ajustée en fonction de son contenu. La taille du pop-up ne peut pas être inférieure à 25 x 25 ni supérieure à 800 x 600.

Pour ajouter un pop-up à votre action de navigateur, créez un fichier HTML contenant le contenu du pop-up. Spécifiez le fichier HTML dans le champ default_popup de browser_action dans le manifeste ou appelez la méthode browserAction.setPopup.

Conseils

Pour un impact visuel optimal, suivez ces consignes :

  • À faire : Utilisez des actions de navigateur pour les fonctionnalités qui sont pertinentes sur la plupart des pages.
  • N'utilisez pas d'actions de navigateur pour les fonctionnalités qui ne sont pertinentes que pour quelques pages. Utilisez plutôt les actions de page.
  • À faire : utilisez des icônes grandes et colorées qui exploitent au mieux l'espace de 16 x 16 dip. Les icônes d'action du navigateur doivent sembler un peu plus grandes et plus lourdes que les icônes d'action de la page.
  • N'essayez pas d'imiter l'icône de menu monochrome de Google Chrome. Cela ne fonctionne pas bien avec les thèmes et, de toute façon, les extensions doivent se démarquer un peu.
  • À faire : Utilisez la transparence alpha pour adoucir les bords de votre icône. Comme de nombreux utilisateurs utilisent des thèmes, votre icône doit être esthétique sur différentes couleurs d'arrière-plan.
  • À ne pas faire : animer constamment votre icône. C'est juste agaçant.

Exemples

Vous trouverez des exemples simples d'utilisation des actions de navigateur dans le répertoire examples/api/browserAction. Pour obtenir d'autres exemples et de l'aide pour afficher le code source, consultez Exemples.

Types

TabDetails

Chrome 88 ou version ultérieure

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é.

Méthodes

disable()

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

Désactive l'action du navigateur pour un onglet.

Paramètres

  • tabId

    number facultatif

    ID de l'onglet pour lequel modifier l'action du navigateur.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

enable()

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

Active l'action du navigateur pour un onglet. Activé par défaut.

Paramètres

  • tabId

    number facultatif

    ID de l'onglet pour lequel modifier l'action du navigateur.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getBadgeBackgroundColor()

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

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

Paramètres

  • détails

    TabDetails

  • callback

    function facultatif

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

    (result: ColorArray) => void

Renvoie

  • Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getBadgeText()

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

Récupère le texte du badge de l'action du navigateur. Si aucun onglet n'est spécifié, le texte du badge non spécifique à un onglet est renvoyé.

Paramètres

  • détails

    TabDetails

  • callback

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise<string>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getPopup()

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

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

Paramètres

  • détails

    TabDetails

  • callback

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise<string>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getTitle()

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

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

Paramètres

  • détails

    TabDetails

  • callback

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise<string>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): 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. Il peut également s'agir d'une chaîne avec une valeur de couleur hexadécimale CSS, par exemple #FF0000 ou #F00 (rouge). Affiche les couleurs avec une opacité totale.

    • tabId

      number facultatif

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

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setBadgeText()

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

Définit le texte du badge pour l'action du navigateur. 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 environ 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.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setIcon()

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

Définit l'icône de l'action du navigateur. L'icône peut être spécifiée en tant que chemin d'accès à un fichier image, en tant que données de pixels d'un élément canevas ou en tant que dictionnaire de l'un de ces éléments. Vous devez indiquer la propriété path ou imageData.

Paramètres

  • détails

    objet

    • imageData

      ImageData | objet facultatif

      Objet ImageData ou dictionnaire {size -> ImageData} représentant une icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image utilisée 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, une image de taille scale * n est 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 une icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image utilisée 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, une image de taille scale * n est 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é.

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 116 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setPopup()

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

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

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é.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

setTitle()

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

Définit le titre de l'action du navigateur. Ce titre 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 du navigateur doit afficher lorsque l'utilisateur pointe dessus.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 88 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onClicked

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

Se déclenche lorsqu'un utilisateur clique sur l'icône d'une action de navigateur. Ne se déclenche pas si l'action de navigateur comporte un pop-up.

Paramètres

  • callback

    fonction

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

    (tab: tabs.Tab) => void