Description
Utilisez l'API chrome.contextMenus
pour ajouter des éléments au menu contextuel de Google Chrome. Vous pouvez choisir les types d'objets auxquels s'appliquent les ajouts du menu contextuel, tels que des images, des liens hypertexte et des pages.
Autorisations
contextMenus
Pour utiliser l'API, vous devez déclarer l'autorisation "contextMenus"
dans le fichier manifeste de votre extension. Vous devez également spécifier une icône de 16 x 16 pixels à afficher à côté de votre élément de menu. Exemple :
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
Concepts et utilisation
Les éléments de menu contextuel peuvent apparaître dans n'importe quel document (ou cadre d'un document), même ceux dont l'URL est file:// ou chrome://. Pour contrôler les documents dans lesquels vos éléments peuvent apparaître, spécifiez le champ documentUrlPatterns
lorsque vous appelez les méthodes create()
ou update()
.
Vous pouvez créer autant d'éléments de menu contextuel que nécessaire, mais si plusieurs éléments de votre extension sont visibles en même temps, Google Chrome les réduit automatiquement en un seul menu parent.
Exemples
Pour essayer cette API, installez l'exemple d'API contexteMenus à partir du dépôt chrome-extension-samples.
Types
ContextType
Les différents contextes dans lesquels un menu peut apparaître. Spécifier "all" équivaut à la combinaison de tous les autres contextes, à l'exception de "launcher". Le contexte "Lanceur d'applications" n'est compatible qu'avec les applications et permet d'ajouter des éléments de menu au menu contextuel qui s'affiche lorsque vous cliquez sur l'icône d'une application dans le lanceur d'applications, la barre des tâches, la station d'accueil, etc. Selon les plates-formes, des limites peuvent s'appliquer à ce qui est réellement pris en charge dans un menu contextuel du lanceur d'applications.
Enum
"all"
"page"
"frame"
"selection"
"link"
"editable"
"image"
"video"
"audio"
"launcher"
"browser_action"
"page_action"
"action"
CreateProperties
Propriétés du nouvel élément du menu contextuel.
Propriétés
-
coché
Booléen facultatif
État initial d'une case à cocher ou d'une case d'option:
true
pour les cases sélectionnées,false
pour les cases non sélectionnées. Vous ne pouvez sélectionner qu'une seule case d'option à la fois dans un groupe donné. -
contexts
[ContextType, ...ContextType[]] facultatif
Liste des contextes dans lesquels cet élément de menu apparaîtra. La valeur par défaut est
['page']
. -
documentUrlPatterns
string[] facultatif
Limite l'application de l'élément aux documents ou aux cadres dont l'URL correspond à l'un des formats indiqués. Pour en savoir plus sur les formats de modèles, consultez Formats de correspondance.
-
activé
Booléen facultatif
Indique si cet élément de menu contextuel est activé ou désactivé. La valeur par défaut est
true
. -
id
string facultatif
Identifiant unique à attribuer à cet élément. Obligatoire pour les pages d'événement. Cet ID ne peut pas être identique à un autre pour cette extension.
-
parentId
chaîne | nombre facultatif
Identifiant d'un élément de menu parent. Cet élément devient l'enfant d'un élément ajouté précédemment.
-
targetUrlPatterns
string[] facultatif
Comme pour
documentUrlPatterns
, les filtres sont basés sur l'attributsrc
des balisesimg
,audio
etvideo
, et sur l'attributhref
des balisesa
. -
title
string facultatif
Texte à afficher dans l'élément. Ce champ est obligatoire, sauf si
type
estseparator
. Lorsque le contexte estselection
, utilisez%s
dans la chaîne pour afficher le texte sélectionné. Par exemple, si la valeur de ce paramètre est "Translate '%s' to Pig Latin" (Traduire '%s' en Pig latin') et que l'utilisateur sélectionne le mot "cool", l'élément de menu contextuel de la sélection est "Translate 'cool' to Pig Latin" (Traduire 'cool" en Pig Latin"). -
Type
ItemType facultatif
Type d'élément de menu. La valeur par défaut est
normal
. -
visible
Booléen facultatif
Indique si l'élément est visible dans le menu.
-
onclick
vide facultatif
Une fonction rappelée lorsque l'utilisateur clique sur l'élément de menu. Cette fonctionnalité n'est pas disponible dans un service worker. Enregistrez un écouteur pour
contextMenus.onClicked
.La fonction
onclick
se présente comme suit :(info: OnClickData, tab: Tab) => {...}
-
infos
Informations sur l'élément sur lequel l'utilisateur a cliqué et contexte dans lequel le clic s'est produit
-
tab
Informations sur l'onglet dans lequel le clic a eu lieu Ce paramètre n'est pas présent pour les applications de plate-forme.
-
ItemType
Type d'élément de menu.
Enum
"normal"
"radio"
"separator"
OnClickData
Informations envoyées lorsque l'utilisateur clique sur un élément du menu contextuel.
Propriétés
-
coché
Booléen facultatif
Indicateur indiquant l'état d'une case à cocher ou d'une case d'option après un clic.
-
modifiable
boolean
Indicateur indiquant si l'élément est modifiable (saisie de texte, zone de texte, etc.).
-
frameId
numéro facultatif
Chrome 51 et versions ultérieuresL'ID du cadre de l'élément dans lequel l'utilisateur a cliqué sur le menu contextuel, s'il se trouvait dans un cadre.
-
frameUrl
string facultatif
URL du cadre de l'élément où l'utilisateur a cliqué sur le menu contextuel, s'il se trouvait dans un cadre.
-
linkUrl
string facultatif
Si l'élément est un lien, l'URL vers laquelle il pointe.
-
mediaType
string facultatif
"image", "vidéo" ou "audio" si le menu contextuel a été activé sur l'un de ces types d'éléments.
-
chaîne | nombre
ID de l'élément de menu sur lequel l'utilisateur a cliqué.
-
pageUrl
string facultatif
URL de la page sur laquelle l'utilisateur a cliqué sur l'élément de menu. Cette propriété n'est pas définie si le clic s'est produit dans un contexte où aucune page n'est en cours, par exemple dans un menu contextuel du lanceur d'applications.
-
parentMenuItemId
chaîne | nombre facultatif
ID parent de l'élément sur lequel l'utilisateur a cliqué, le cas échéant.
-
selectionText
string facultatif
Texte de la sélection de contexte, le cas échéant.
-
srcUrl
string facultatif
Sera présent pour les éléments ayant une URL "src".
-
wasChecked
Booléen facultatif
Indicateur indiquant l'état d'une case à cocher ou d'une case d'option avant le clic.
Propriétés
ACTION_MENU_TOP_LEVEL_LIMIT
Nombre maximal d'éléments de l'extension de niveau supérieur pouvant être ajoutés au menu contextuel des actions de l'extension. Au-delà de cette limite, les éléments sont ignorés.
Valeur
6
Méthodes
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
Crée un élément de menu contextuel. Si une erreur se produit lors de la création, elle risque de ne pas être détectée avant le déclenchement du rappel de création. Les détails sont disponibles dans runtime.lastError
.
Paramètres
-
createProperties
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
nombre | chaîne
Identifiant du nouvel élément.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Supprime un élément de menu contextuel.
Paramètres
-
chaîne | nombre
ID de l'élément de menu contextuel à supprimer.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 123 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.
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
Supprime tous les éléments de menu contextuel ajoutés par cette extension.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 123 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.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
Met à jour un élément de menu contextuel créé précédemment.
Paramètres
-
id
chaîne | nombre
Identifiant de l'article à mettre à jour.
-
updateProperties
objet
Propriétés à mettre à jour. Accepte les mêmes valeurs que la fonction
contextMenus.create
.-
coché
Booléen facultatif
-
contexts
[ContextType, ...ContextType[]] facultatif
-
documentUrlPatterns
string[] facultatif
-
activé
Booléen facultatif
-
parentId
chaîne | nombre facultatif
Identifiant de l'élément qui deviendra le parent de cet élément. Remarque: Vous ne pouvez pas définir un élément pour qu'il devienne l'enfant de son propre descendant.
-
targetUrlPatterns
string[] facultatif
-
title
string facultatif
-
Type
ItemType facultatif
-
visible
Booléen facultatif
Chrome 62 ou version ultérieureIndique si l'élément est visible dans le menu.
-
onclick
vide facultatif
La fonction
onclick
se présente comme suit :(info: OnClickData, tab: Tab) => {...}
-
infosChrome 44 ou version ultérieure
-
tabChrome 44 ou version ultérieure
Informations sur l'onglet dans lequel le clic a eu lieu Ce paramètre n'est pas présent pour les applications de plate-forme.
-
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 123 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.
Événements
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
Déclenché lorsqu'un utilisateur clique sur un élément du menu contextuel
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(info: OnClickData, tab?: tabs.Tab) => void
-
infos
-
tab
tabs.Tab facultatif
-