Description
Utilisez l'API chrome.action
pour contrôler l'icône de l'extension dans la barre d'outils Google Chrome.
Disponibilité
Fichier manifeste
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 3
comme "manifest_version"
et incluez
la clé "action"
dans le 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"
(ainsi que ses enfants) est facultative. Lorsqu'elle n'est pas incluse, l'extension reste affichée dans la barre d'outils pour permettre l'accès 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
Icône
L'icône est l'image principale dans la barre d'outils de votre extension. Elle est définie par la touche "default_icon"
dans
la clé "action"
de votre fichier manifeste. Les icônes doivent faire 16 pixels indépendants de l'appareil (DIP) en largeur et en hauteur.
La clé "default_icon"
est un dictionnaire des tailles des chemins d'accès aux images. Chrome utilise ces icônes
choisir l'échelle d'image à utiliser. Si aucune correspondance exacte n'est trouvée, Chrome sélectionne
disponible et la met à l'échelle pour l'adapter à l'image, ce qui peut affecter sa qualité.
Parce que les appareils dont les facteurs d'échelle moins courants tels que x1,5 ou x1,2 sont de plus en plus
commun, nous vous conseillons de proposer plusieurs tailles pour vos icônes. Cette opération
pérennise votre extension face aux changements potentiels de taille d'affichage des icônes. Toutefois,
si vous ne fournissez qu'une seule taille, la clé "default_icon"
peut également être définie sur
avec le chemin d'accès à une seule icône au lieu d'un dictionnaire.
Vous pouvez aussi appeler action.setIcon()
pour définir l'icône de votre extension de façon programmatique.
en spécifiant un chemin d'accès d'image différent ou en fournissant une icône générée dynamiquement à l'aide du canevas HTML
, ou, s'il s'agit d'un service worker d'extension, le paramètre hors écran
canevas.
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 Blink peut de rendu, y compris PNG, JPEG, BMP, ICO, etc. Le format SVG n'est pas accepté. Les extensions non empaquetées doivent utiliser des images PNG.
Info-bulle (titre)
L'info-bulle (ou titre) s'affiche lorsque l'utilisateur place le pointeur de la souris sur l'icône de l'extension dans la section barre d'outils. Il est également inclus dans le texte accessible énoncé par les lecteurs d'écran lorsque le bouton est le focus.
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 le définir par programmation en appelant action.setTitle()
.
Badge
Les actions peuvent éventuellement afficher un "badge" : une partie de texte est superposée à l'icône. Cela vous permet mettre à jour l'action pour 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é, le texte du badge ne doit pas comporter plus de quatre caractères.
Pour créer un badge, définissez-le de façon programmatique en appelant action.setBadgeBackgroundColor()
et
action.setBadgeText()
Il n'existe pas de paramètre de badge par défaut dans le fichier manifeste. Valeurs de couleur du badge
Il peut s'agir d'un tableau de quatre entiers compris entre 0 et 255 qui constituent la couleur RVBA de la
ou d'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
Une fenêtre pop-up d'action s'affiche lorsque l'utilisateur clique sur le bouton d'action de l'extension dans la section barre d'outils. Le pop-up peut contenir le contenu HTML de votre choix, et sa taille s'adapte automatiquement son contenu. La taille de la fenêtre 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"
dans
manifest.json
. Si cette propriété est présente, elle doit pointer vers un chemin d'accès relatif dans l'extension.
. Il peut également être mis à jour de manière dynamique pour pointer vers un chemin d'accès 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'une
utilisez la propriété tabId
dans les méthodes de définition de l'API action
. Par exemple, pour
définissez 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
est omise, le paramètre est traité comme un paramètre global. Selon l'onglet
ont la priorité sur les paramètres généraux.
État "Activé"
Par défaut, les actions de la barre d'outils sont activées (cliquables) sur chaque onglet. Vous pouvez contrôler ce paramètre à l'aide des
action.enable()
et action.disable()
. Cela affecte uniquement si la fenêtre pop-up (le cas échéant) ou
action.onClicked
événement est envoyé à 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 de chrome-extension-samples. un dépôt de clés.
Afficher un pop-up
Il est courant qu'une extension affiche un pop-up lorsque l'utilisateur clique sur une action de l'extension. À
Implémentez ceci dans votre propre extension, déclarez le pop-up dans votre manifest.json
et spécifiez le
le contenu que Chrome doit afficher dans le pop-up.
// 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
Les extensions présentent souvent leur fonctionnalité principale à l'aide de la méthode action. L'exemple suivant illustre ce modèle. 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 a fonctionné 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 des actions avec declarativeContent
Cet exemple montre comment la logique d'arrière-plan d'une extension peut (a) désactiver une action par défaut et (b) Utilisez declarativeContent pour activer l'action 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 aucune tabulation n'est spécifiée, l'état qui n'est pas spécifique à la tabulation est renvoyé.
UserSettings
Ensemble des paramètres spécifiés par l'utilisateur concernant l'action d'une extension.
Propriétés
-
isOnToolbar
booléen
Indique si l'icône d'action de l'extension est visible dans les fenêtres du navigateur barre d'outils racine (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
ID de l'onglet pour lequel vous souhaitez modifier l'action.
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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. Les actions sont activées par défaut.
Paramètres
-
tabId
numéro facultatif
ID de l'onglet pour lequel vous souhaitez modifier l'action.
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
function facultatif
Le paramètre
callback
se présente comme suit:(result: ColorArray) => void
-
résultat
-
Renvoie
-
Promise<browserAction.ColorArray>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 aucune tabulation n'est spécifiée, le texte du badge qui n'est pas spécifique à la tabulation 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
function facultatif
Le paramètre
callback
se présente comme suit:(result: string) => void
-
résultat
chaîne
-
Renvoie
-
Promise<string>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
function facultatif
Le paramètre
callback
se présente comme suit:(result: ColorArray) => void
-
résultat
-
Renvoie
-
Promise<browserAction.ColorArray>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 l'ensemble de documents HTML en tant que pop-up pour cette action.
Paramètres
-
détails
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(result: string) => void
-
résultat
chaîne
-
Renvoie
-
Promise<string>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
function facultatif
Le paramètre
callback
se présente comme suit:(result: string) => void
-
résultat
chaîne
-
Renvoie
-
Promise<string>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Affiche les paramètres spécifiés par l'utilisateur concernant l'action d'une extension.
Paramètres
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(userSettings: UserSettings) => void
-
userSettings
-
Renvoie
-
Promise<UserSettings>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 globalement 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 "Activé".
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:(isEnabled: boolean) => void
-
isEnabled
booléen
"True" si l'action de l'extension est activée.
-
Renvoie
-
Promise<boolean>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Ouvre le pop-up de l'extension. Entre Chrome 118 et Chrome 126, cette option n'est disponible que pour les extensions installées par règle.
Paramètres
-
options
OpenPopupOptions facultatif
Spécifie les options d'ouverture du pop-up.
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
string | 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, le rouge opaque correspondant à#FF0000
ou#F00
. -
tabId
numéro facultatif
Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 s'affiche en haut de l'icône.
Paramètres
-
détails
objet
-
tabId
numéro facultatif
Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
texte
chaîne facultatif
Vous pouvez transmettre n'importe quel nombre de caractères, mais vous ne pouvez en transmettre que quatre environ. Si une chaîne vide (
''
) est transmise, le texte du badge est effacé. SitabId
est spécifié et quetext
est nul, le texte de l'onglet spécifié est effacé et le texte global du badge est utilisé par défaut.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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
string | 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, le rouge opaque correspondant à#FF0000
ou#F00
. Si vous ne définissez pas cette valeur, une couleur sera choisie automatiquement, qui contraste avec la couleur d'arrière-plan du badge afin que le texte soit visible. Les couleurs avec des valeurs alpha équivalentes à 0 ne seront pas définies et renverront une erreur. -
tabId
numéro facultatif
Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 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
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 taillescale
* 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 taillescale
* 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
numéro facultatif
Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Chrome 96 ou version ultérieureLes promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 en tant que pop-up lorsque l'utilisateur clique sur l'icône de l'action.
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
numéro facultatif
Limite la modification au moment où un onglet spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 spécifique est sélectionné. Se réinitialise automatiquement lorsque l'onglet est fermé.
-
titre
chaîne
Chaîne sur laquelle l'action doit s'afficher lorsque l'utilisateur passe la souris dessus.
-
-
rappel
function facultatif
Le paramètre
callback
se présente comme suit:() => void
Renvoie
-
Promise<void>
Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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.