chrome.browserAction

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 du navigateur peut comporter une info-bulle, un badge et un pop-up.

Disponibilité

<ph type="x-smartling-placeholder"></ph> &amp;leq; MV2

Dans la figure suivante, le carré multicolore à droite de la barre d'adresse représente l'icône d'une action du navigateur. Un pop-up s'affiche sous l'icône.

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

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 n'importe quelle icône de taille à utiliser dans Chrome, et Chrome sélectionnera l'icône la plus proche et s'adaptera à la taille appropriée pour remplir l'espace de 16 creux. Toutefois, si la taille exacte n'est pas indiquée, la mise à l'échelle peut rendre l'icône moins détaillée ou floue.

Étant donné que les appareils avec des facteurs d'échelle moins courants tels que x1,5 ou x1,2 sont de plus en plus courants, vous êtes encouragé à fournir plusieurs tailles pour vos icônes. Cela garantit également que si la taille d'affichage de l'icône est modifié, vous n'avez pas besoin d'intervenir pour proposer d'autres icônes !

L'ancienne syntaxe pour enregistrer l'icône par défaut est toujours prise en charge:

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

Composantes de l'interface utilisateur

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

Icône

Dans Chrome, les icônes d'action du navigateur mesurent 16 pouces (pixels indépendants de l'appareil) en largeur et en hauteur. Plus grande les icônes sont redimensionnées pour s’adapter, mais pour de meilleurs résultats, utilisez une icône carrée à 16 creux.

Vous pouvez définir l'icône de deux manières: en utilisant une image statique ou l'élément de canevas HTML5. En utilisant les images statiques sont plus faciles à utiliser pour les applications simples, mais vous pouvez créer des interfaces utilisateur plus dynamiques, telles que une animation fluide grâce à l'élément canevas.

Les images statiques peuvent utiliser n'importe quel format compatible avec WebKit, y compris BMP, GIF, ICO, JPEG ou PNG. Pour non empaquetées, les images doivent être au format PNG.

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

Pour afficher correctement l'icône lorsque la densité en 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 tailles différentes. L'image réelle à l'écran sera sélectionné parmi l'ensemble pour s'adapter au mieux à la taille en pixels de 16 creux. Le jeu d'icônes peut contenir n'importe quelle spécification d'icône de taille, et Chrome sélectionnera la plus appropriée.

Info-bulle

Pour définir l'info-bulle, utilisez le champ default_title de default_title 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 du navigateur peuvent éventuellement afficher un badge, c'est-à-dire un texte superposé sur l'icône. Les badges permettent de mettre à jour facilement l'action du navigateur pour afficher une petite quantité d'informations sur le l'état de l'extension.

L'espace étant 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 du navigateur s'affiche, celle-ci s'affiche lorsque l'utilisateur clique sur l'icône de l'extension. La peut contenir n'importe quel contenu HTML, et sa taille est automatiquement ajustée pour s'adapter à son contenu. La taille de la fenêtre pop-up ne doit pas être inférieure à 25 x 25 ni supérieure à 800 x 600.

Pour ajouter un pop-up à l'action de votre navigateur, créez un fichier HTML avec son contenu. Spécifiez le paramètre HTML dans le champ default_popup de default_popup du fichier manifeste ou appelez la méthode browserAction.setPopup.

Conseils

Pour un impact visuel optimal, suivez ces consignes:

  • Utilisez les actions du navigateur pour les fonctionnalités pertinentes sur la plupart des pages.
  • N'utilisez pas les actions du navigateur pour des fonctionnalités pertinentes pour quelques pages seulement. Utiliser la page actions à la place.
  • Utilisez de grandes icônes colorées pour tirer le meilleur parti de cet espace de 16 x 16 dip. 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 de thèmes et, de toute façon, les extensions doivent se démarquer un peu.
  • Utilisez la transparence alpha pour ajouter des bords doux à votre icône. Étant donné que de nombreuses personnes utilisent des thèmes, doit être agréable sur une variété de couleurs d'arrière-plan.
  • N'animez pas constamment votre icône. C'est juste ennuyeux.

Exemples

Vous trouverez des exemples simples d'utilisation des actions du navigateur dans examples/api/browserAction . Pour obtenir d'autres exemples et obtenir de l'aide sur l'affichage du code source, consultez la section Exemples.

Types

ColorArray

Type

[number, number, number, number]

ImageDataType

Données de pixels pour une image. Doit être un objet ImageData. (par exemple, à partir d'un élément canvas).

Type

ImageData

TabDetails

Chrome (version 88 ou ultérieure)

Propriétés

  • tabId

    numéro facultatif

    ID de l'onglet pour lequel interroger l'état. Si aucune tabulation n'est spécifiée, l'état qui n'est pas spécifique à la tabulation est renvoyé.

Méthodes

disable()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

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

Paramètres

  • tabId

    numéro facultatif

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

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

enable()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Active l'action du navigateur pour un onglet. La valeur par défaut est activée.

Paramètres

  • tabId

    numéro facultatif

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

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

Renvoie

  • Promise&lt;ColorArray&gt;

    Chrome (version 88 ou ultérieure)

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

getBadgeText()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

Récupère le texte du badge de l'action du navigateur. Si aucune tabulation n'est spécifiée, le texte du badge qui n'est pas spécifique à la tabulation est renvoyé.

Paramètres

  • détails

    TabDetails

  • rappel

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise&lt;string&gt;

    Chrome (version 88 ou ultérieure)

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

getPopup()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

  • détails

    TabDetails

  • rappel

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise&lt;string&gt;

    Chrome (version 88 ou ultérieure)

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

getTitle()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

  • détails

    TabDetails

  • rappel

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise&lt;string&gt;

    Chrome (version 88 ou ultérieure)

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

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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 forment 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

      numéro facultatif

      Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

setBadgeText()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Définit le texte du badge pour l'action du navigateur. Le badge s'affiche en haut de l'icône.

Paramètres

  • détails

    objet

    • tabId

      numéro facultatif

      Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.

    • texte

      chaîne facultatif

      Vous pouvez transmettre n'importe quel nombre de caractères, mais vous ne pouvez en transmettre que quatre environ. 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 le texte global du badge est utilisé par défaut.

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

setIcon()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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 de canevas ou en tant que dictionnaire de l'un de ces éléments. Vous devez spécifier la propriété path ou imageData.

Paramètres

  • détails

    objet

    • imageData

      ImageData | objet facultatif

      Un objet ImageData ou un 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é en pixels de l'écran. Si le nombre de pixels d'image pouvant tenir dans une unité d'espace à l'écran est égal à scale, une image de scale * n est sélectionnée, où n est la taille de l'icône dans l'UI. Vous devez spécifier au moins une image. Notez que 'details.imageData = foo' équivaut à 'details.imageData = {'16': foo}'

    • chemin d'accès

      string | objet facultatif

      Un chemin d'accès d'image relatif ou un dictionnaire {size -> chemin relatif de l'image} 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é en pixels de l'écran. Si le nombre de pixels d'image pouvant tenir dans une unité d'espace à l'écran est égal à scale, une image de scale * n est sélectionnée, où n est la taille de l'icône dans l'UI. Vous devez spécifier au moins une image. Notez que "details.path = foo" équivaut à 'details.path = {'16': foo}'

    • tabId

      numéro facultatif

      Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 116 et versions ultérieures

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

setPopup()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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 vers le fichier HTML à afficher dans une fenêtre pop-up. S'il est défini sur une chaîne vide (''), aucun pop-up ne s'affiche.

    • tabId

      numéro facultatif

      Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

setTitle()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Définit le titre de l'action du navigateur. Ce titre apparaît dans l'info-bulle.

Paramètres

  • détails

    objet

    • tabId

      numéro facultatif

      Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.

    • titre

      chaîne

      Chaîne que l'action du navigateur doit afficher lorsque l'utilisateur passe la souris dessus.

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<void>

    Chrome (version 88 ou ultérieure)

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

Événements

onClicked

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

Déclenché lorsqu'un utilisateur clique sur une icône d'action du navigateur. Ne se déclenche pas si l'action du navigateur affiche un pop-up.

Paramètres

  • rappel

    fonction

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

    (tab: tabs.Tab) => void