Cette page a été traduite par l'API Cloud Translation.

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

Garantie de disponibilité

&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. Une fenêtre pop-up s'affiche sous l'icône.

Si vous souhaitez créer une icône qui n'est pas toujours active, utilisez une action sur la page plutôt qu'une action de navigateur.

Manifest

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 l'adaptera à la taille appropriée pour remplir l'espace de 16 creux. Toutefois, si la taille exacte n'est pas indiquée, cette mise à l'échelle peut entraîner une perte de détails de l'icône ou son apparence floue.

Étant donné que les appareils avec des facteurs de scaling moins courants tels que 1,5 ou 1,2x deviennent plus courants, nous vous recommandons d'indiquer plusieurs tailles pour vos icônes. Cela garantit également que si la taille d'affichage des icônes est modifiée, vous n'avez pas besoin de fournir d'autres icônes.

L'ancienne syntaxe d'enregistrement de 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 comporter une icône, une info-bulle, un badge et un pop-up.

Icône

Dans Chrome, les icônes d'action du navigateur ont une largeur et une hauteur de 16 dips (pixels indépendants de l'appareil). 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 dips.

Vous pouvez définir l'icône de deux manières: à l'aide d'une image statique ou de l'élément de canevas HTML5. L'utilisation d'images statiques est plus facile pour les applications simples, mais vous pouvez créer des interfaces utilisateur plus dynamiques, telles que des animations fluides, à l'aide de l'élément canevas.

Les images statiques peuvent être dans n'importe quel format d'affichage proposé par WebKit, 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 default_icon 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 tailles différentes. L'image réelle à afficher sera sélectionnée dans l'ensemble pour s'adapter au mieux à la taille en pixels de 16 (dip). L'ensemble d'icônes peut contenir des spécifications d'icône de n'importe quelle taille, et Chrome sélectionne la plus appropriée.

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 la section Internationalisation.

Badge

Les actions du navigateur peuvent éventuellement afficher un badge, c'est-à-dire du 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.

L'espace disponible sur le badge étant limité, il 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 dans un pop-up, celui-ci s'affiche lorsque l'utilisateur clique sur l'icône de l'extension. La fenêtre pop-up peut contenir n'importe quel contenu HTML. Elle est automatiquement dimensionnée pour s'adapter à son contenu. La fenêtre pop-up ne doit pas être inférieure à 25 x 25 ni à 800 x 600.

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

Conseils

Pour obtenir 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. Utilisez plutôt les actions sur la page.
Utilisez de grandes icônes colorées pour tirer le meilleur parti de l'espace de 16 x 16. Les icônes d'action du navigateur doivent sembler un peu plus grandes et plus lourdes que les icônes d'action de 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 devraient se démarquer un peu.
Utilisez la transparence alpha pour ajouter des bords souples à votre icône. Comme beaucoup de gens utilisent des thèmes, votre icône doit s'afficher correctement sur différentes couleurs d'arrière-plan.
N'animez pas l'icône en permanence. C'est juste ennuyeux.

Exemples

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

Types

ColorArray

Type

[nombre,nombre,nombre,nombre]

ImageDataType

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

Type

ImageData

TabDetails

Chrome 88 et versions ultérieures

Propriétés

tabId

numéro facultatif

ID de l'onglet pour lequel interroger l'état. Si aucun onglet n'est spécifié, l'état non spécifique à un onglet est renvoyé.

Méthodes

disable()

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 vous souhaitez modifier l'action du navigateur.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

enable()

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 vous souhaitez modifier l'action du navigateur.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

getBadgeBackgroundColor()

Promesse

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

détails

TabDetails
rappel

fonction facultative

Le paramètre callback se présente comme suit :
```
(result: ColorArray)=>void
```
- résultat
  
  ColorArray

Renvoie

Promise<ColorArray>

Chrome 88 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.

getBadgeText()

Promesse

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

détails

TabDetails
rappel

fonction facultative

Le paramètre callback se présente comme suit :
```
(result: string)=>void
```
- résultat
  
  chaîne

Renvoie

Promesse<chaîne>

Chrome 88 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.

getPopup()

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

fonction facultative

Le paramètre callback se présente comme suit :
```
(result: string)=>void
```
- résultat
  
  chaîne

Renvoie

Promesse<chaîne>

Chrome 88 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.

getTitle()

Promesse

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

Paramètres

détails

TabDetails
rappel

fonction facultative

Le paramètre callback se présente comme suit :
```
(result: string)=>void
```
- résultat
  
  chaîne

Renvoie

Promesse<chaîne>

Chrome 88 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.

setBadgeBackgroundColor()

Promesse

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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

Paramètres

détails

objet
- couleur
  
  chaîne|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
  
  numéro facultatif
  
  Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

setBadgeText()

Promesse

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

Paramètres

détails

objet
- tabId
  
  numéro facultatif
  
  Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
- text
  
  string facultatif
  
  Il est possible de transmettre autant de caractères que vous le souhaitez, mais seuls quatre caractères 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 la valeur text est nulle, le texte de l'onglet spécifié est effacé et le texte du badge global est utilisé par défaut.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

setIcon()

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
  
  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é en pixels de l'écran. Si le nombre de pixels de l'image qui tiennent dans une unité d'espace à l'écran est égal à scale, une image de taille scale * n est sélectionnée, où n correspond à la taille de l'icône dans l'interface utilisateur. Vous devez spécifier au moins une image. Notez que "details.imageData = foo" est équivalent à "details.imageData = {'16': foo}".
- chemin d'accès
  
  chaîne|objet facultatif
  
  Chemin d'accès d'image relatif 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é en pixels de l'écran. Si le nombre de pixels de l'image qui tiennent dans une unité d'espace à l'écran est égal à scale, une image de taille scale * n est sélectionnée, où n correspond à la taille de l'icône dans l'interface utilisateur. Vous devez spécifier au moins une image. Notez que "details.path = foo" est équivalent à "details.path = {'16': foo}".
- tabId
  
  numéro facultatif
  
  Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
rappel

fonction facultative

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<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()

Promesse

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

Définit le document HTML à ouvrir dans une fenêtre pop-up lorsque l'utilisateur clique sur l'icône d'action du navigateur.

Paramètres

détails

objet
- pop-up
  
  chaîne
  
  Chemin d'accès relatif au fichier HTML à afficher dans une fenêtre pop-up. Si elle est définie sur la chaîne vide (''), aucune fenêtre pop-up ne s'affiche.
- tabId
  
  numéro facultatif
  
  Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

setTitle()

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 particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
- title
  
  chaîne
  
  Chaîne que l'action du navigateur doit afficher lorsque l'utilisateur passe la souris dessus.
rappel

fonction facultative

Chrome 67 et versions ultérieures

Le paramètre callback se présente comme suit :
```
()=>void
```

Renvoie

Promise<void>

Chrome 88 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.

Événements

onClicked

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

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

Paramètres

rappel

function

Le paramètre callback se présente comme suit :
```
(tab: tabs.Tab)=>void
```
- tab
  
  tabs.Tab

chrome.browserAction

Description

Garantie de disponibilité

Manifest

Composantes de l'interface utilisateur

Icône

Info-bulle

Badge

Fenêtre pop-up

Conseils

Exemples

Types

ColorArray

Type

ImageDataType

Type

TabDetails

Propriétés

Méthodes

disable()

Paramètres

Renvoie

enable()

Paramètres

Renvoie

getBadgeBackgroundColor()

Paramètres

Renvoie

getBadgeText()

Paramètres

Renvoie

getPopup()

Paramètres

Renvoie

getTitle()

Paramètres

Renvoie

setBadgeBackgroundColor()

Paramètres

Renvoie

setBadgeText()

Paramètres

Renvoie

setIcon()

Paramètres

Renvoie

setPopup()

Paramètres

Renvoie

setTitle()

Paramètres

Renvoie

Événements

onClicked

Paramètres