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é
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
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()
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
-
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érieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
Récupère le titre de l'action sur la page.
Paramètres
-
détails
-
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érieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
hide()
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
Nombre
ID de l'onglet pour lequel vous souhaitez modifier l'action sur la page.
-
rappel
fonction facultative
Chrome 67 et versions ultérieuresLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 101 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
setIcon()
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 taillescale
* 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 taillescale
* 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
Nombre
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érieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
setPopup()
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
Nombre
ID de l'onglet pour lequel vous souhaitez modifier l'action sur la page.
-
-
rappel
fonction facultative
Chrome 67 et versions ultérieuresLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 101 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
setTitle()
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
Nombre
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érieuresLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 101 et versions ultérieuresLes promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.
show()
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
Nombre
ID de l'onglet pour lequel vous souhaitez modifier l'action sur la page.
-
rappel
fonction facultative
Chrome 67 et versions ultérieuresLe paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 101 et versions ultérieuresLes 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.