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 les options ajoutées au menu contextuel s'appliquent, comme les images, les liens hypertextes et les 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 du menu contextuel peuvent apparaître dans n'importe quel document (ou cadre dans un document), même ceux avec des URL 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 vous le souhaitez, mais si plusieurs éléments de votre extension sont visibles en même temps, Google Chrome les réduit automatiquement dans un seul menu parent.

Exemples

Pour essayer cette API, installez l'exemple d'API contextMenus à partir du dépôt chrome-extension-samples.

Types

ContextType

Chrome 44 ou version ultérieure

Différents contextes dans lesquels un menu peut s'afficher. Spécifier "all" équivaut à la combinaison de tous les autres contextes, à l'exception de "launcher". Le contexte "lanceur" 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 de l'application dans le lanceur/la barre des tâches/le dock, etc. Différentes plates-formes peuvent imposer des limites à ce qui est réellement compatible dans un menu contextuel de lanceur.

Énumération

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 ou version ultérieure

Propriétés du nouvel élément de menu contextuel.

Propriétés

  • coché

    booléen facultatif

    État initial d'une case à cocher ou d'un bouton radio: true pour la sélection, false pour la non-sélection. 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 s'affichera. 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 donnés. Pour en savoir plus sur les formats de modèle, 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

    chaîne facultatif

    Identifiant unique à attribuer à cet élément. Obligatoire pour les pages d'événement. Ne doit pas être identique à un autre ID de cette extension.

  • parentId

    chaîne | nombre facultatif

    ID d'un élément de menu parent, ce qui en fait un enfant d'un élément précédemment ajouté.

  • targetUrlPatterns

    string[] facultatif

    Comme documentUrlPatterns, filtres basés sur l'attribut src des balises img, audio et video, et sur l'attribut href des balises a.

  • titre

    chaîne facultatif

    Texte à afficher dans l'élément. Cet élément est obligatoire, sauf si type est défini sur 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 "Traduire "%s" en langage argotique" et que l'utilisateur sélectionne le mot "cool", l'élément du menu contextuel correspondant est "Traduire "cool" en langage argotique".

  • 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

    void facultatif

    Fonction appelée en retour lorsque l'utilisateur clique sur l'élément de menu. Cette fonctionnalité n'est pas disponible dans un service worker. Vous devez plutôt enregistrer 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 sur le contexte dans lequel le clic s'est produit.

    • tabulation

      Tabulation

      Détails de l'onglet sur lequel le clic a été effectué. 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.

Énumération

"normal"

"checkbox"

"radio"

"séparateur"

OnClickData

Informations envoyées lorsqu'un utilisateur clique sur un élément de menu contextuel.

Propriétés

  • coché

    booléen facultatif

    Indicateur indiquant l'état d'une case à cocher ou d'une option après avoir cliqué dessus.

  • modifiable

    booléen

    Indicateur indiquant si l'élément est modifiable (champ de texte, zone de texte, etc.).

  • frameId

    number facultatif

    Chrome 51 ou version ultérieure

    ID du cadre de l'élément sur lequel le menu contextuel a été cliqué, s'il se trouvait dans un cadre.

  • frameUrl

    chaîne facultatif

    URL du cadre de l'élément sur lequel l'utilisateur a cliqué sur le menu contextuel, s'il se trouvait dans un cadre.

  • linkUrl

    chaîne facultatif

    Si l'élément est un lien, l'URL qu'il pointe vers.

  • mediaType

    chaîne facultatif

    "Image", "Vidéo" ou "Audio" si le menu contextuel a été activé sur l'un de ces types d'éléments.

  • menuItemId

    chaîne | nombre

    ID de l'élément de menu ayant enregistré le clic.

  • pageUrl

    chaîne 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ù il n'y a pas de page actuelle, par exemple dans un menu contextuel de lanceur.

  • parentMenuItemId

    chaîne | nombre facultatif

    ID parent (le cas échéant) de l'élément sur lequel l'utilisateur a cliqué.

  • selectionText

    chaîne facultatif

    Texte de la sélection de contexte, le cas échéant.

  • srcUrl

    chaîne facultatif

    Présent pour les éléments avec une URL "src".

  • wasChecked

    booléen facultatif

    Indicateur indiquant l'état d'une case à cocher ou d'une case d'option avant qu'un utilisateur ne clique dessus.

Propriétés

ACTION_MENU_TOP_LEVEL_LIMIT

Nombre maximal d'éléments d'extension de niveau supérieur pouvant être ajoutés à un menu contextuel d'action d'extension. Les éléments au-delà de cette limite seront 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 peut ne pas être détectée avant le déclenchement du rappel de création. Les détails se trouvent dans runtime.lastError.

Paramètres

  • createProperties

    CreateProperties

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • nombre | chaîne

    Identifiant de l'élément nouvellement créé.

remove()

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

Supprime un élément de menu contextuel.

Paramètres

  • menuItemId

    chaîne | nombre

    ID de l'élément de menu contextuel à supprimer.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 123 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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 facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 123 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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

    chaîne | nombre

    ID 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

      ID de l'élément à définir comme parent de cet élément. Remarque: Vous ne pouvez pas définir un élément pour qu'il devienne enfant de son propre descendant.

    • targetUrlPatterns

      string[] facultatif

    • titre

      chaîne 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

      void facultatif

      La fonction onclick se présente comme suit : 

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

      • infos

        OnClickData

        Chrome 44 ou version ultérieure
      • tabulation

        Tabulation

        Chrome 44 ou version ultérieure

        Détails de l'onglet sur lequel le clic a été effectué. Ce paramètre n'est pas présent pour les applications de plate-forme.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Chrome 123 ou version ultérieure

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout 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 de menu contextuel.

Paramètres