chrome.pageAction

Description

Utilisez l'API chrome.pageAction pour placer des icônes dans la barre d'outils principale de Google Chrome, à droite de la barre d'adresse. Les actions sur la page correspondent aux actions qui peuvent être effectuées sur la page actuelle, mais qui ne s'appliquent pas à toutes les pages. Les actions sur la page sont grisées lorsqu'elles sont inactives.

Garantie de disponibilité

≤ MV2

Voici quelques exemples :

  • S'abonner au flux RSS de cette page
  • Créer un diaporama à partir des photos de cette page

Dans la capture d'écran suivante, l'icône RSS représente une action sur la page qui vous permet de vous abonner au flux RSS pour la page actuelle.

Les actions masquées sur une page sont grisées. Par exemple, le flux RSS ci-dessous est grisé, car vous ne pouvez pas vous y abonner pour la page actuelle:

Envisagez plutôt d'utiliser une action de navigateur afin que les utilisateurs puissent toujours interagir avec votre extension.

Manifest

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

{
  "name": "My extension",
  ...
  "page_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
  },
  ...
}

É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. Chrome sélectionne l'écran le plus proche et le dimensionne pour remplir l'espace de 16 pixels. 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. Toutefois, si la différence de taille est trop extrême, cette mise à l'échelle peut entraîner une perte de détails de l'icône ou son apparence floue.

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

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

Composantes de l'interface utilisateur

Comme les actions du navigateur, les actions sur les pages peuvent avoir une icône, une info-bulle et un pop-up, mais pas de badges. En outre, les actions sur la page peuvent être grisées. Pour en savoir plus sur les icônes, les info-bulles et les fenêtres pop-up, consultez l'article consacré à l'interface utilisateur des actions du navigateur.

Pour qu'une action sur la page apparaisse et soit grisée, utilisez respectivement les méthodes pageAction.show et pageAction.hide. Par défaut, une action sur une page est grisée. Lorsque vous l'affichez, vous spécifiez l'onglet dans lequel l'icône doit apparaître. L'icône reste visible jusqu'à ce que l'onglet soit fermé ou qu'elle commence à afficher une autre URL (par exemple, parce que l'utilisateur clique sur un lien).

Conseils

Pour obtenir un impact visuel optimal, suivez ces consignes:

  • Utilisez les actions sur les pages pour les fonctionnalités pertinentes pour quelques pages seulement.
  • N'utilisez pas les actions de page pour les fonctionnalités pertinentes pour la plupart des pages. Utilisez plutôt les actions du navigateur.
  • N'animez pas l'icône en permanence. C'est juste ennuyeux.

Types

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

getPopup()

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

Récupère le document HTML défini en tant que pop-up pour cette action sur la page.

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 101 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.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

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

hide()

Promesse 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

Masque l'action sur la page. Les actions de page masquées apparaissent toujours dans la barre d'outils Chrome, mais sont grisées.

Paramètres

  • tabId

    number

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

  • rappel

    fonction facultative

    Chrome 67 et versions ultérieures

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

    ()=>void

Renvoie

  • Promise<void>

    Chrome 101 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.pageAction.setIcon(
  details: object,
  callback?: function,
)

Définit l'icône de l'action sur la page. 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 provenant 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

    • iconIndex

      numéro facultatif

      Obsolète. Cet argument est ignoré.

    • imageData

      ImageData|objet facultatif

      Objet ImageData ou dictionnaire {size -> ImageData} représentant l'icône à définir. Si l'icône est un dictionnaire, l'image à utiliser 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 d'écran est égal à scale, l'image de taille scale * n sera 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 l'icône à définir. Si l'icône est un dictionnaire, l'image à utiliser 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 d'écran est égal à scale, l'image de taille scale * n sera 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

      number

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

  • rappel

    fonction facultative

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

    ()=>void

Renvoie

  • Promise<void>

    Chrome 101 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.pageAction.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 sur la page.

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

      number

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

  • rappel

    fonction facultative

    Chrome 67 et versions ultérieures

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

    ()=>void

Renvoie

  • Promise<void>

    Chrome 101 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.pageAction.setTitle(
  details: object,
  callback?: function,
)

Définit le titre de l'action sur la page. Cette information s'affiche dans une info-bulle sur l'action associée à la page.

Paramètres

  • détails

    objet

    • tabId

      number

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

    • title

      chaîne

      Chaîne de l'info-bulle.

  • rappel

    fonction facultative

    Chrome 67 et versions ultérieures

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

    ()=>void

Renvoie

  • Promise<void>

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

show()

Promesse 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

Affiche l'action sur la page. L'action sur la page s'affiche chaque fois que l'onglet est sélectionné.

Paramètres

  • tabId

    number

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

  • rappel

    fonction facultative

    Chrome 67 et versions ultérieures

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

    ()=>void

Renvoie

  • Promise<void>

    Chrome 101 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.pageAction.onClicked.addListener(
  callback: function,
)

Déclenché lorsqu'un utilisateur clique sur une icône d'action sur une page Cet événement ne se déclenchera pas si l'action sur la page s'affiche dans un pop-up.

Paramètres

  • rappel

    function

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

    (tab: tabs.Tab)=>void