Description
Utilisez l'API chrome.action
pour contrôler l'icône de l'extension dans la barre d'outils Google Chrome.
Garantie de disponibilité
Manifest
Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.
"action"
Pour utiliser l'API chrome.action
, spécifiez un "manifest_version"
3
et incluez la clé "action"
dans votre fichier manifeste.
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
La clé "action"
(avec ses enfants) est facultative. Si l'extension n'est pas incluse, elle reste affichée dans la barre d'outils pour permettre d'accéder au menu de l'extension. C'est pourquoi nous vous recommandons de toujours inclure au moins les clés "action"
et "default_icon"
.
Concepts et utilisation
Composantes de l'interface utilisateur
Icon
L'icône est l'image principale de la barre d'outils de votre extension. Elle est définie par la clé "default_icon"
dans la clé "action"
de votre fichier manifeste. Les icônes doivent avoir une largeur et une hauteur de 16 pixels indépendants des appareils (DIP).
La clé "default_icon"
est un dictionnaire de tailles et de chemins d'accès aux images. Chrome utilise ces icônes pour
choisir l'échelle d'image à utiliser. Si aucune correspondance exacte n'est trouvée, Chrome sélectionne la version disponible la plus proche et l'adapte à l'image, ce qui peut affecter la qualité de l'image.
Étant donné que les appareils avec des facteurs de scaling moins courants, tels que 1,5 ou 1,2x, deviennent de plus en plus courants, nous vous encourageons à fournir plusieurs tailles d'icônes. Cela permet également de protéger votre extension contre d'éventuels changements de taille d'affichage des icônes.
Vous pouvez également appeler action.setIcon()
pour définir l'icône de votre extension de manière programmatique en spécifiant un autre chemin d'accès à l'image ou en fournissant une icône générée dynamiquement à l'aide de l'élément de canevas HTML ou, si vous le définissez à partir d'un service worker d'extension, de l'API hors écran canvas.
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });
Pour les extensions empaquetées (installées à partir d'un fichier .crx), les images peuvent être dans la plupart des formats que le moteur de rendu Blink peut afficher, y compris PNG, JPEG, BMP, ICO, etc. Le format SVG n'est pas compatible. Les extensions non empaquetées doivent utiliser des images PNG.
Info-bulle (titre)
L'info-bulle, ou titre, apparaît lorsque l'utilisateur maintient le pointeur de la souris sur l'icône de l'extension dans la barre d'outils. Il est également inclus dans le texte accessible prononcé par les lecteurs d'écran lorsque le bouton est sélectionné.
L'info-bulle par défaut est définie à l'aide du champ "default_title"
de la clé "action"
dans manifest.json
.
Vous pouvez également la définir par programmation en appelant action.setTitle()
.
Badge
Les actions peuvent éventuellement afficher un "badge", c'est-à-dire une portion de texte superposée à l'icône. Cela vous permet de mettre à jour l'action afin d'afficher une petite quantité d'informations sur l'état de l'extension, comme un compteur. Le badge comporte un composant texte et une couleur d'arrière-plan. L'espace étant limité, nous vous recommandons de ne pas dépasser quatre caractères pour le texte du badge.
Pour créer un badge, définissez-le par programmation en appelant action.setBadgeBackgroundColor()
et action.setBadgeText()
. Le fichier manifeste ne contient pas de paramètre de badge par défaut. Les valeurs de couleur du badge peuvent être un tableau de quatre entiers compris entre 0 et 255 qui constituent la couleur RVBA du badge, ou une chaîne avec une valeur de couleur CSS.
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Fenêtre pop-up
La fenêtre pop-up d'une action s'affiche lorsque l'utilisateur clique sur le bouton d'action de l'extension dans la barre d'outils. Le pop-up peut contenir n'importe quel contenu HTML. Il sera automatiquement dimensionné pour s'adapter à son contenu. La taille du pop-up doit être comprise entre 25 x 25 et 800 x 600 pixels.
La fenêtre pop-up est initialement définie par la propriété "default_popup"
de la clé "action"
du fichier manifest.json
. Si cette propriété est présente, elle doit pointer vers un chemin d'accès relatif dans le répertoire d'extension. Il peut également être mis à jour de manière dynamique pour pointer vers un chemin relatif différent à l'aide de la méthode action.setPopup()
.
Cas d'utilisation
État par onglet
Les actions d'extension peuvent avoir différents états pour chaque onglet. Pour définir la valeur d'un onglet individuel, utilisez la propriété tabId
dans les méthodes de paramétrage de l'API action
. Par exemple, pour définir le texte du badge pour un onglet spécifique, procédez comme suit:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Si la propriété tabId
n'est pas définie, le paramètre est considéré comme un paramètre global. Les paramètres propres aux onglets sont prioritaires sur les paramètres généraux.
État d'activation
Par défaut, les actions de la barre d'outils sont activées (cliquables) dans chaque onglet. Vous pouvez contrôler cela à l'aide des méthodes action.enable()
et action.disable()
. Cela n'affecte que l'envoi du pop-up (le cas échéant) ou de l'événement action.onClicked
à votre extension. Cela n'affecte pas la présence de l'action dans la barre d'outils.
Exemples
Les exemples suivants illustrent des utilisations courantes des actions dans les extensions. Pour essayer cette API, installez l'exemple d'API Action à partir du dépôt chrome-extension-samples.
Afficher un pop-up
Il est fréquent qu'une extension affiche une fenêtre pop-up lorsque l'utilisateur clique sur l'action associée. Pour implémenter cette fonctionnalité dans votre propre extension, déclarez le pop-up dans le fichier manifest.json
et spécifiez le contenu que Chrome doit y afficher.
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
Injecter un script de contenu lors d'un clic
Un modèle courant pour les extensions consiste à exposer leur fonctionnalité principale à l'aide de l'action de l'extension. L'exemple suivant illustre ce schéma. Lorsque l'utilisateur clique sur l'action, l'extension injecte un script de contenu dans la page actuelle. Le script de contenu affiche ensuite une alerte pour vérifier que tout fonctionne comme prévu.
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
Émuler les actions avec déclarativeContent
Cet exemple montre comment la logique d'arrière-plan d'une extension peut (a) désactiver une action par défaut et (b) utiliser declarativeContent pour l'activer sur des sites spécifiques.
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
Types
OpenPopupOptions
Propriétés
-
windowId
numéro facultatif
ID de la fenêtre dans laquelle ouvrir le pop-up d'action. Si aucune valeur n'est spécifiée, la valeur par défaut est la fenêtre actuellement active.
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é.
UserSettings
Ensemble de paramètres spécifiés par l'utilisateur concernant l'action d'une extension.
Propriétés
-
isOnToolbar
boolean
Indique si l'icône d'action de l'extension est visible dans la barre d'outils supérieure des fenêtres du navigateur (c'est-à-dire si l'extension a été "épinglée" par l'utilisateur).
Méthodes
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
Désactive l'action pour un onglet.
Paramètres
-
tabId
numéro facultatif
L'ID de l'onglet pour lequel vous souhaitez modifier l'action.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Active l'action pour un onglet. Par défaut, les actions sont activées.
Paramètres
-
tabId
numéro facultatif
L'ID de l'onglet pour lequel vous souhaitez modifier l'action.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Récupère la couleur d'arrière-plan de l'action.
Paramètres
-
détails
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: ColorArray)=>void
-
résultat
-
Renvoie
-
Promise<browserAction.ColorArray>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Récupère le texte du badge de l'action. Si aucun onglet n'est spécifié, le texte du badge qui n'est pas propre à un onglet est renvoyé. Si displayActionCountAsBadgeText est activé, un texte d'espace réservé est renvoyé, sauf si l'autorisation declarativeNetRequestFeedback est présente ou si un texte de badge spécifique à l'onglet a été fourni.
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>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Récupère la couleur du texte de l'action.
Paramètres
-
détails
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: ColorArray)=>void
-
résultat
-
Renvoie
-
Promise<browserAction.ColorArray>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Récupère le document HTML défini en tant que pop-up pour cette action.
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>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Récupère le titre de l'action.
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>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Renvoie les paramètres spécifiés par l'utilisateur concernant l'action d'une extension.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(userSettings: UserSettings)=>void
-
userSettings
-
Renvoie
-
Promise<UserSettings>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Indique si l'action d'extension est activée pour un onglet (ou de manière globale si aucun tabId
n'est fourni). Les actions activées à l'aide de declarativeContent
uniquement renvoient toujours la valeur "false".
Paramètres
-
tabId
numéro facultatif
ID de l'onglet pour lequel vous souhaitez vérifier l'état d'activation.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(isEnabled: boolean)=>void
-
isEnabled
boolean
"True" si l'action de l'extension est activée.
-
Renvoie
-
Promise<boolean>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Ouvre la fenêtre pop-up de l'extension.
Paramètres
-
options
OpenPopupOptions facultatif
Spécifie les options d'ouverture du pop-up.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Définit la couleur d'arrière-plan du badge.
Paramètres
-
détails
objet
-
couleur
chaîne|ColorArray
Tableau de quatre entiers compris dans la plage [0 255] qui constituent la couleur RVBA du badge. Par exemple, le rouge opaque correspond à
[255, 0, 0, 255]
. Il peut également s'agir d'une chaîne avec une valeur CSS (rouge opaque correspondant à#FF0000
ou#F00
). -
tabId
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Définit le texte du badge pour l'action. Le badge est affiché au-dessus de l'icône.
Paramètres
-
détails
objet
-
tabId
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
text
string facultatif
Il est possible de transmettre autant de caractères que vous le souhaitez, mais seuls quatre caractères environ peuvent tenir dans l'espace. Si une chaîne vide (
''
) est transmise, le texte du badge est effacé. SitabId
est spécifié et que la valeurtext
est nulle, le texte de l'onglet spécifié est effacé et le texte du badge global est utilisé par défaut.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
Définit la couleur du texte du badge.
Paramètres
-
détails
objet
-
couleur
chaîne|ColorArray
Tableau de quatre entiers compris dans la plage [0 255] qui constituent la couleur RVBA du badge. Par exemple, le rouge opaque correspond à
[255, 0, 0, 255]
. Il peut également s'agir d'une chaîne avec une valeur CSS (rouge opaque correspondant à#FF0000
ou#F00
). Si vous ne définissez pas cette valeur, une couleur sera automatiquement choisie pour contraster avec la couleur d'arrière-plan du badge, de sorte que le texte soit visible. Les couleurs dont les valeurs alpha correspondent à 0 ne seront pas définies et renverront une erreur. -
tabId
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
Définit l'icône de l'action. 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
-
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
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setPopup()
chrome.action.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 de l'action.
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
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Définit le titre de l'action. Cela s'affiche dans l'info-bulle.
Paramètres
-
détails
objet
-
tabId
numéro facultatif
Limite la modification au moment où un onglet particulier est sélectionné. Réinitialise automatiquement lorsque l'onglet est fermé.
-
title
chaîne
Chaîne que l'action doit afficher lorsque l'utilisateur passe la souris dessus.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :()=>void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onClicked
chrome.action.onClicked.addListener(
callback: function,
)
Déclenché lorsqu'un utilisateur clique sur une icône d'action Cet événement ne se déclenchera pas si l'action s'affiche dans un pop-up.