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 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. Par ailleurs, vous devez spécifier une icône de 16 par 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 d'un document), même ceux comportant l'attribut file:// ou chrome://. Pour contrôler les documents dans lesquels vos éléments peuvent apparaître, indiquez la 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 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 de chrome-extension-samples. un dépôt de clés.

Types

ContextType

Chrome (version 44 ou ultérieure)

Les 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 "Lanceur d'applications" Le contexte n'est pris en charge que par les applications et est utilisé pour 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 d'applications, la barre des tâches, la station d'accueil, etc. Différentes plates-formes peuvent limiter les éléments réellement pris en charge dans un menu contextuel du lanceur d'applications.

Énumération

"tous"

"page"

"cadre"

"selection"

"lien"

"modifiable"

"image"

"vidéo"

"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 une case sélectionnée, false pour une case non sélectionnée. 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'élément à s'appliquer uniquement aux documents ou aux cadres dont l'URL correspond à l'un des formats indiqués. Pour en savoir plus sur les formats de modèle, consultez la section 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. L'ID ne peut pas être identique à un autre pour cette extension.

  • parentId

    string | numéro facultatif

    ID d'un élément de menu parent. cela fait de l'élément un 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.

  • titre

    chaîne facultatif

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

    Fonction rappelée lorsque l'utilisateur clique sur l'élément de menu. Elle 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 contexte où il s'est produit.

    • tabulation

      Tabulation

      Détails de l'onglet dans lequel le clic s'est produit Ce paramètre n'est pas présent pour les applications de plate-forme.

ItemType

Chrome (version 44 ou ultérieure)

Type d'élément de menu.

Énumération

"normal"

"case à cocher"

"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 case d'option après un clic.

  • modifiable

    booléen

    Indicateur indiquant si l'élément peut être modifié (saisie de texte, zone de texte, etc.).

  • frameId

    numéro facultatif

    Chrome (version 51 ou ultérieure)

    L'ID du cadre de l'élément où l'utilisateur a cliqué sur le menu contextuel, s'il était dans un cadre.

  • frameUrl

    chaîne facultatif

    URL du frame de l'élément où l'utilisateur a cliqué sur le menu contextuel, s'il était dans un frame.

  • linkUrl

    chaîne facultatif

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

  • mediaType

    chaîne facultatif

    Valeurs possibles : "image", "video" ou "audio" si le menu contextuel a été activé sur l'un de ces types d'éléments.

  • menuItemId

    string | numéro

    ID de l'élément de menu sur lequel l'utilisateur a cliqué.

  • pageUrl

    chaîne facultatif

    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 alors qu'il n'y a pas de page active, par exemple dans le menu contextuel du lanceur d'applications.

  • parentMenuItemId

    string | numéro facultatif

    ID du parent, le cas échéant, pour l'élément ayant enregistré un clic.

  • selectionText

    chaîne facultatif

    Texte utilisé pour la sélection du contexte, le cas échéant.

  • srcUrl

    chaîne facultatif

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

  • wasChecked

    Booléen facultatif

    Indicateur indiquant l'état d'une case à cocher ou d'un élément d'option avant qu'un clic ne soit effectué.

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. Tous 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 ne sera peut-être pas détectée tant que le rappel de création ne se déclenchera pas. vous trouverez plus d'informations dans runtime.lastError.

Paramètres

  • createProperties

    CreateProperties

  • rappel

    function facultatif

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

    () => void

Renvoie

  • numéro | chaîne

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

remove()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

Supprime un élément de menu contextuel.

Paramètres

  • menuItemId

    string | numéro

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

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 123 et versions ultérieures

    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.

removeAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

Paramètres

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 123 et versions ultérieures

    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.

update()

<ph type="x-smartling-placeholder"></ph> 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 | numéro

    Identifiant de l'élément à 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

      string | numéro 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 en faire l'enfant de son propre descendant.

    • targetUrlPatterns

      string[] facultatif

    • titre

      chaîne facultatif

    • type

      ItemType facultatif

    • visible

      Booléen facultatif

      Chrome (version 62 ou 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 (version 44 ou ultérieure)
      • tabulation

        Tabulation

        Chrome (version 44 ou ultérieure)

        Détails de l'onglet dans lequel le clic s'est produit Ce paramètre n'est pas présent pour les applications de plate-forme.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

    Chrome 123 et versions ultérieures

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

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

Paramètres