chrome.contextMenus

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

Chrome 44 ou version ultérieure

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

Chrome 123 et versions ultérieures

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'attribut src des balises img, audio et video, et sur l'attribut href des balises a.

  • title

    string facultatif

    Texte à afficher dans l'élément. Ce champ est obligatoire, sauf si type est separator. Lorsque le contexte est selection, 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

      OnClickData

      Informations sur l'élément sur lequel l'utilisateur a cliqué et contexte dans lequel le clic s'est produit

    • 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

Chrome 44 ou version ultérieure

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érieures

    L'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.

  • menuItemId

    string|number

    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

    CreateProperties

  • rappel

    fonction facultative

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

    ()=>void

Renvoie

  • number|string

    Identifiant du nouvel élément.

remove()

Promesse 
chrome.contextMenus.remove(
  menuItemId: string|number,
  callback?: function,
)

Supprime un élément de menu contextuel.

Paramètres

  • menuItemId

    string|number

    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érieures

    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.

removeAll()

Promesse 
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érieures

    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.

update()

Promesse 
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

    string|number

    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érieure

      Indique si l'élément est visible dans le menu.

    • onclick

      vide facultatif

      La fonction onclick se présente comme suit : 

      (info: OnClickData,tab: Tab)=> {...}

      • infos

        OnClickData

        Chrome 44 ou version ultérieure
      • Chrome 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érieures

    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.contextMenus.onClicked.addListener(
  callback: function,
)

Déclenché lorsqu'un utilisateur clique sur un élément du menu contextuel

Paramètres