chrome.pageAction

refresh date: 2026-09-25 robots: noindex

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 de page représentent les actions qui peuvent être effectuées sur la page actuelle, mais qui ne s'appliquent pas à toutes les pages. Les actions de page sont grisées lorsqu'elles sont inactives.

Disponibilité

≤ MV2

Voici quelques exemples :

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

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

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

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

Fichier manifeste

Enregistrez l'action sur la 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 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. Chrome sélectionnera l'icône la plus proche et la redimensionnera pour remplir l'espace de 16 dip. 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. Toutefois, si la différence de taille est trop importante, cette mise à l'échelle peut entraîner une perte de détails ou un aspect flou de l'icône.

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

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

Parties de l'UI

Comme les actions de navigateur, les actions de page peuvent comporter une icône, une info-bulle et un pop-up, mais pas de badge. De plus, les actions de page peuvent être grisées. Pour en savoir plus sur les icônes, les info-bulles et les pop-ups, consultez la section UI de l'action du navigateur.

Vous pouvez afficher une action sur la page et la griser à l'aide des méthodes pageAction.show et pageAction.hide, respectivement. Par défaut, une action de page apparaît 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'il commence à afficher une autre URL (par exemple, parce que l'utilisateur clique sur un lien).

Conseils

Pour un impact visuel optimal, suivez ces consignes :

  • À faire : utilisez des actions sur la page pour les fonctionnalités qui ne sont pertinentes que pour quelques pages.
  • N'utilisez pas d'actions de page pour les fonctionnalités qui sont pertinentes pour la plupart des pages. Utilisez plutôt les actions de navigateur.
  • À ne pas faire : animer constamment votre icône. C'est juste agaçant.

Types

ImageDataType

Données de pixels d'une image. Il doit s'agir d'un objet ImageData (par exemple, d'un élément canvas).

Type

ImageData

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

getPopup()

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

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

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

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

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

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

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

Paramètres

  • tabId

    nombre

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

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

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

Définit l'icône de l'action sur la page. L'icône peut être spécifiée soit comme le chemin d'accès à un fichier image, soit comme les données de pixels d'un élément canevas, soit comme un dictionnaire de l'un ou l'autre. Vous devez spécifier la propriété path ou imageData.

Paramètres

  • détails

    objet

    • iconIndex

      number 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 spécifiée sous forme de dictionnaire, l'image réelle à utiliser 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, l'image de taille scale * n sera 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 l'icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image réelle à utiliser 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, l'image de taille scale * n sera 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

      nombre

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

  • callback

    function facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 101 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.pageAction.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 de l'action sur la page.

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

      nombre

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

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

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

Définit le titre de l'action sur la page. Il s'affiche dans une info-bulle au-dessus de l'action sur la page.

Paramètres

  • détails

    objet

    • tabId

      nombre

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

    • titre

      chaîne

      Chaîne de l'info-bulle.

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

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

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

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

Paramètres

  • tabId

    nombre

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

  • callback

    function facultatif

    Chrome 67 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

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

Se déclenche lorsqu'un utilisateur clique sur une icône d'action sur la page. Cet événement ne se déclenche pas si l'action de la page comporte un pop-up.

Paramètres

  • callback

    fonction

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

    (tab: tabs.Tab) => void