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 éléments ajoutés au menu contextuel, comme les images, les liens hypertexte 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 de menu contextuel peuvent apparaître dans n'importe quel document (ou frame 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 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 contextMenus à partir du dépôt chrome-extension-samples.

Types

ContextType

Chrome 44 et versions ultérieures

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" n'est compatible qu'avec les applications. Il 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 sur ce qui est réellement pris en charge dans un menu contextuel du lanceur.

Énumération

"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 de menu contextuel.

Propriétés

  • coché

    booléen facultatif

    État initial d'une case à cocher ou d'une case d'option : true pour sélectionné, false pour non sélectionné. Une seule case d'option peut être sélectionnée à 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

    Restreint 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

    chaîne facultative

    Identifiant unique à attribuer à cet élément. Obligatoire pour les pages d'événements. Il ne peut pas être identique à un autre ID pour cette extension.

  • parentId

    string | number facultatif

    ID d'un élément de menu parent. L'élément devient ainsi un enfant d'un élément ajouté précédemment.

  • targetUrlPatterns

    string[] facultatif

    Semblable à 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 facultative

    Texte à afficher dans l'élément. Ce paramètre 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 Pig Latin" et que l'utilisateur sélectionne le mot "cool", l'élément de menu contextuel pour la sélection est "Traduire 'cool' en Pig Latin".

  • type

    ItemType facultatif

    Type de l'é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 optional

    Fonction de rappel appelée lorsque l'utilisateur clique sur l'élément de menu. Cette méthode 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 l'utilisateur a cliqué. Ce paramètre n'est pas présent pour les applications de plate-forme.

ItemType

Chrome 44 et versions ultérieures

Type de l'élément de menu.

Énumération

"normal"

"checkbox"

"radio"

"separator"

OnClickData

Informations envoyées lorsqu'un élément de menu contextuel est sélectionné.

Propriétés

  • coché

    booléen facultatif

    Indicateur de l'état d'une case à cocher ou d'une case d'option après un clic.

  • modifiable

    booléen

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

  • frameId

    number facultatif

    Chrome 51 et versions ultérieures

    L'ID du frame de l'élément sur lequel l'utilisateur a cliqué pour ouvrir le menu contextuel, s'il se trouvait dans un frame.

  • frameUrl

    chaîne facultative

    URL du frame de l'élément sur lequel l'utilisateur a cliqué avec le bouton droit de la souris, s'il se trouvait dans un frame.

  • linkUrl

    chaîne facultative

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

  • mediaType

    chaîne facultative

    L'une des valeurs "image", "video" 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

    chaîne facultative

    URL de la page sur laquelle l'élément de menu a été cliqué. 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, comme dans un menu contextuel du lanceur d'applications.

  • parentMenuItemId

    string | number facultatif

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

  • selectionText

    chaîne facultative

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

  • srcUrl

    chaîne facultative

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

  • wasChecked

    booléen facultatif

    Indicateur de l'état d'une case à cocher ou d'un bouton radio avant que l'utilisateur ne clique dessus.

Propriétés

ACTION_MENU_TOP_LEVEL_LIMIT

Nombre maximal d'éléments d'extension de premier niveau pouvant être ajoutés au menu contextuel d'une action d'extension. Tous les éléments au-delà de cette limite seront ignorés.

Valeur

6

Méthodes

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
): number | string

Crée un élément de menu contextuel. Si une erreur se produit lors de la création, elle ne sera peut-être détectée qu'au moment du déclenchement du rappel de création. Les détails seront disponibles dans runtime.lastError.

Paramètres

  • createProperties

    CreateProperties

  • callback

    function facultatif

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

    () => void

Renvoie

  • number | string

    Identifiant de l'élément récemment créé.

remove()

chrome.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

Supprime un élément de menu contextuel.

Paramètres

  • menuItemId

    string | number

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

Renvoie

  • Promise<void>

    Chrome 123 et versions ultérieures

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

Supprime tous les éléments de menu contextuel ajoutés par cette extension.

Renvoie

  • Promise<void>

    Chrome 123 et versions ultérieures

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

Met à jour un élément de menu contextuel créé précédemment.

Paramètres

  • id

    string | number

    ID de l'article à modifier.

  • 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

      string | number facultatif

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

    • targetUrlPatterns

      string[] facultatif

    • titre

      chaîne facultative

    • type

      ItemType facultatif

    • visible

      booléen facultatif

      Chrome 62 et versions ultérieures

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

    • onclick

      void optional

      La fonction onclick se présente comme suit : 

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

      • infos

        OnClickData

        Chrome 44 et versions ultérieures
      • tabulation

        Tabulation

        Chrome 44 et versions ultérieures

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

Renvoie

  • Promise<void>

    Chrome 123 et versions ultérieures

Événements

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

Déclenché lorsqu'un élément de menu contextuel est sélectionné.

Paramètres