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 active, mais qui ne s'appliquent pas à toutes les pages. Les actions sur la page sont grisées lorsqu'elles sont inactives.

Disponibilité

<ph type="x-smartling-placeholder"></ph> &amp;leq; 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 pour la page actuelle.

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

Envisagez plutôt d'effectuer une action dans le navigateur, afin que les utilisateurs puissent toujours interagir avec votre .

Fichier manifeste

Enregistrez l'action de 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 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. Chrome sélectionnera la version la plus proche et la mettra à l'échelle pour remplir l'espace de 16 creux. Cela garantit également que si la taille d'affichage de l'icône est modifiée, avez besoin de travail supplémentaire pour fournir des icônes différentes ! En revanche, si la différence de taille est trop extrême, cette mise à l'échelle peut faire perdre de détails ou sembler floue.

L'ancienne syntaxe pour enregistrer 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

Tout comme les actions du navigateur, les actions sur les pages peuvent contenir une icône, une info-bulle et un pop-up. ils ne peuvent pas avoir de badges, . De plus, les actions sur la page peuvent être grisées. Vous pouvez trouver des informations sur les icônes, des info-bulles et des fenêtres pop-up en lisant les actions du navigateur.

Vous pouvez afficher et grisé une action sur la page à l'aide des boutons pageAction.show et pageAction.hide, respectivement. Par défaut, une action sur une page est grisée. Lorsque vous vous spécifiez l'onglet dans lequel l'icône doit apparaître. L'icône reste visible jusqu'à ce que l'onglet est fermée ou commence à afficher une URL différente (parce que l'utilisateur clique sur un lien, par exemple).

Conseils

Pour un impact visuel optimal, suivez ces consignes:

  • Utilisez les actions sur la page pour des fonctionnalités qui n'ont de sens que pour quelques pages.
  • N'utilisez pas les actions sur la page pour des fonctionnalités pertinentes pour la plupart des pages. Utiliser les actions du navigateur à la place.
  • N'animez pas constamment votre icône. C'est juste ennuyeux.

Types

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

getPopup()

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

Récupère l'ensemble de documents HTML en tant que pop-up pour cette action de page.

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

<ph type="x-smartling-placeholder"></ph> 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

    function facultatif

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

    (result: string) => void

    • résultat

      chaîne

Renvoie

  • Promise&lt;string&gt;

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

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

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

Paramètres

  • tabId

    Nombre

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

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<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()

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

Définit l'icône de l'action de 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 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

      Un objet ImageData ou un dictionnaire {size -> ImageData} représentant l'icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image à utiliser 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 taille scale * n sera sélectionnée, n étant 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 l'icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image à utiliser 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 taille scale * n sera sélectionnée, n étant 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

      Nombre

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

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.pageAction.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 de la page.

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

      Nombre

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

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<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()

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

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

Paramètres

  • détails

    objet

    • tabId

      Nombre

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

    • titre

      chaîne

      Chaîne de l'info-bulle.

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<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()

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

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

Paramètres

  • tabId

    Nombre

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

  • rappel

    function facultatif

    Chrome (version 67 ou ultérieure)

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

    () => void

Renvoie

  • Promesse<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 l'icône d'action d'une page. Cet événement ne se déclenchera pas si l'action sur la page est associée à un pop-up.

Paramètres

  • rappel

    fonction

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

    (tab: tabs.Tab) => void