chrome.browserAction

Description

Disponibilité

Dans l'image suivante, le carré multicolore à droite de la barre d'adresse est l'icône d'une action du navigateur. Un 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 de page au lieu d'une action de navigateur.

Fichier manifeste

Enregistrez votre action 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 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 avec des facteurs d'échelle moins courants, comme 1,5 x ou 1,2 x, 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 plus besoin de fournir d'autres icônes.

L'ancienne syntaxe d'enregistrement de 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" }
  },
  ...
}

Composants de l'UI

Une action dans le navigateur peut être associée à 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 large et de haut. 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: à l'aide d'une image statique ou de l'élément canvas HTML5. L'utilisation d'images statiques est plus simple pour les applications simples, mais vous pouvez créer des UI plus dynamiques (telles qu'une animation fluide) à l'aide de l'élément canvas.

Les images statiques peuvent être au format que WebKit peut afficher, y compris BMP, GIF, ICO, JPEG ou PNG. Pour les extensions non décompressé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 parmi l'ensemble pour s'adapter au mieux à la taille de pixel de 16 dip. L'ensemble 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 browser_action dans le fichier manifeste ou appelez la méthode browserAction.setTitle. Vous pouvez spécifier des chaînes spécifiques à la langue pour le champ default_title. Pour en savoir plus, consultez Internationalisation.

Badge

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

Étant donné que l'espace disponible sur le badge est 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 de browserAction.setBadgeBackgroundColor, respectivement.

Fenêtre pop-up

Si une action du navigateur est associée à 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 adaptée à son contenu. La fenêtre pop-up ne doit pas être inférieure à 25 x 25 px ni supérieure à 800 x 600 px.

Pour ajouter un pop-up à votre action dans le 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 fichier manifeste, ou appelez la méthode browserAction.setPopup.

Conseils

Pour un impact visuel optimal, suivez ces consignes:

• Utilisez des actions de navigateur pour les fonctionnalités qui ont du sens sur la plupart des pages.
• N'utilisez pas d'actions de navigateur pour des fonctionnalités qui ne sont pertinentes que pour quelques pages. Utilisez plutôt les actions de page.
• Faites-le : utilisez des icônes grandes et colorées qui exploitent au maximum l'espace de 16 x 16 dp. 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. 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, votre icône doit être agréable sur différentes 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 le répertoire examples/api/browserAction. Pour obtenir d'autres exemples et de l'aide pour afficher le code source, consultez la section Exemples.

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

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

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

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

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

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

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

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

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

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