chrome.contextMenus

Descripción

Usa la API de chrome.contextMenus para agregar elementos al menú contextual de Google Chrome. Puedes elegir a qué tipos de objetos se aplican las incorporaciones de tu menú contextual, como imágenes, hipervínculos y páginas.

Permisos

contextMenus

Para usar la API, debes declarar el permiso "contextMenus" en el manifiesto de tu extensión. Además, debes especificar un ícono de 16 por 16 píxeles para mostrar junto al elemento de menú. Por ejemplo:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

Conceptos y uso

Los elementos del menú contextual pueden aparecer en cualquier documento (o marco dentro de un documento), incluso en aquellos que tengan URLs file:// o chrome://. Para controlar en qué documentos pueden aparecer tus elementos, especifica el campo documentUrlPatterns cuando llames a los métodos create() o update().

Puedes crear todos los elementos de menú contextual que necesites, pero si hay más de uno de tu extensión a la vez, Google Chrome los contrae automáticamente en un único menú superior.

Ejemplos

Para probar esta API, instala el ejemplo de la API de contextoMenus del repositorio chrome-extension-samples.

Tipos

ContextType

Chrome 44 y versiones posteriores

Los diferentes contextos en los que puede aparecer un menú. Especificar "todos" equivale a la combinación de todos los demás contextos, excepto "selector". El contexto del "selector" solo es compatible con las apps y se usa para agregar elementos de menú al menú contextual que aparece cuando se hace clic en el ícono de la app en el selector, la barra de tareas, el conector, etc. Las diferentes plataformas pueden limitar lo que realmente admite el menú contextual de un selector.

Enum

"browser_action"

"page_action"

CreateProperties

Chrome 123 y versiones posteriores

Propiedades del nuevo elemento de menú contextual.

Propiedades

  • elemento marcado

    booleano opcional

    El estado inicial de una casilla de verificación o un botón de selección: true para el valor seleccionado, false para el no seleccionado. Solo se puede elegir un botón de selección a la vez en un grupo determinado.

  • contextos

    [ContextType,...ContextType[]] opcional

    Lista de contextos en los que aparecerá este elemento de menú. La configuración predeterminada es ['page'].

  • documentUrlPatterns

    string[] opcional

    Restringe el elemento para que se aplique únicamente a documentos o marcos cuya URL coincida con uno de los patrones especificados. Para obtener detalles sobre los formatos de patrones, consulta Coincidencia de patrones.

  • habilitado

    booleano opcional

    Indica si este elemento de menú contextual está habilitado o inhabilitado. La configuración predeterminada es true.

  • id

    cadena opcional

    Es el ID único que se asignará a este elemento. Obligatorio para las páginas de eventos. No puede ser igual a otro ID para esta extensión.

  • parentId

    cadena|número opcional

    El ID de un elemento de menú superior; esto hace que el elemento sea un elemento secundario de un elemento agregado anteriormente.

  • targetUrlPatterns

    string[] opcional

    De manera similar a documentUrlPatterns, los filtros se basan en el atributo src de las etiquetas img, audio y video, y en el atributo href de las etiquetas a.

  • título

    cadena opcional

    El texto que se mostrará en el elemento. Es obligatorio, a menos que type sea separator. Cuando el contexto sea selection, usa %s dentro de la cadena para mostrar el texto seleccionado. Por ejemplo, si el valor de este parámetro es "Traducir '%s' a Pig Latin" y el usuario selecciona la palabra "genial", el elemento del menú contextual de la selección será "Traducir 'cool' a Pig Latin".

  • Tipo

    ItemType opcional

    Es el tipo de elemento del menú. La configuración predeterminada es normal.

  • visible

    booleano opcional

    Indica si el elemento es visible en el menú.

  • onclick

    void opcional

    Una función a la que se vuelve a llamar cuando se hace clic en el elemento de menú. No está disponible en un service worker. En su lugar, debes registrar un objeto de escucha para contextMenus.onClicked.

    La función onclick se ve de la siguiente manera: 

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

    • Información sobre el elemento en el que se hizo clic y el contexto donde se hizo el clic.

    • tab

      Tab

      Los detalles de la pestaña en la que se produjo el clic Este parámetro no está presente para apps de plataforma.

ItemType

Chrome 44 y versiones posteriores

Es el tipo de elemento del menú.

Enum

"radio"

OnClickData

Información que se envía cuando se hace clic en un elemento del menú contextual.

Propiedades

  • elemento marcado

    booleano opcional

    Una marca que indica el estado de una casilla de verificación o de un elemento de selección después de que se hace clic en él

  • modificable

    boolean

    Una marca que indica si el elemento se puede editar (entrada de texto, área de texto, etcétera).

  • frameId

    número opcional

    Chrome 51 y versiones posteriores

    El ID del marco del elemento en el que se hizo clic en el menú contextual, si estaba en un marco.

  • frameUrl

    cadena opcional

    La URL del marco del elemento donde se hizo clic en el menú contextual, si estaba en un marco.

  • linkUrl

    cadena opcional

    Si el elemento es un vínculo, la URL a la que dirige.

  • mediaType

    cadena opcional

    Puede ser “imagen”, “video” o “audio” si el menú contextual se activó en uno de estos tipos de elementos.

  • menuItemId

    string|number

    El ID del elemento de menú en el que se hizo clic.

  • pageUrl

    cadena opcional

    La URL de la página en la que se hizo clic en el elemento de menú. Esta propiedad no se establece si el clic se produjo en un contexto en el que no hay una página actual, como en un menú contextual de un selector.

  • parentMenuItemId

    cadena|número opcional

    Es el ID superior del elemento en el que se hizo clic.

  • selectionText

    cadena opcional

    El texto para la selección de contexto, si corresponde.

  • srcUrl

    cadena opcional

    Estará presente para los elementos con una URL “src”.

  • wasChecked

    booleano opcional

    Una marca que indica el estado de una casilla de verificación o de un elemento de selección antes de que se hiciera clic en él.

Propiedades

ACTION_MENU_TOP_LEVEL_LIMIT

Es la cantidad máxima de elementos de extensión de nivel superior que se pueden agregar a un menú contextual de acciones de extensión. Se ignorará cualquier elemento que supere este límite.

Valor

6

Métodos

create()

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

Crea un nuevo elemento de menú contextual. Si se produce un error durante la creación, es posible que no se detecte hasta que se active la devolución de llamada de creación. Los detalles estarán en runtime.lastError.

Parámetros

  • createProperties

    CreateProperties

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    ()=>void

Devuelve

  • number|string

    El ID del elemento recién creado.

remove()

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

Elimina un elemento del menú contextual.

Parámetros

  • menuItemId

    string|number

    El ID del elemento del menú contextual que se quitará.

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    ()=>void

Devuelve

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

removeAll()

Promesa 
chrome.contextMenus.removeAll(
  callback?: function,
)

Quita todos los elementos del menú contextual que agregó esta extensión.

Parámetros

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    ()=>void

Devuelve

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

update()

Promesa 
chrome.contextMenus.update(
  id: string|number,
  updateProperties: object,
  callback?: function,
)

Actualiza un elemento de menú contextual creado anteriormente.

Parámetros

  • id

    string|number

    El ID del artículo que se actualizará.

  • updateProperties

    objeto

    Las propiedades que se actualizarán. Acepta los mismos valores que la función contextMenus.create.

    • elemento marcado

      booleano opcional

    • contextos

      [ContextType,...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • habilitado

      booleano opcional

    • parentId

      cadena|número opcional

      El ID del elemento que se convertirá en el elemento superior de este. Nota: No puedes establecer un elemento para que se convierta en un elemento secundario de su propio elemento subordinado.

    • targetUrlPatterns

      string[] opcional

    • título

      cadena opcional

    • Tipo

      ItemType opcional

    • visible

      booleano opcional

      Chrome 62 y versiones posteriores

      Indica si el elemento es visible en el menú.

    • onclick

      void opcional

      La función onclick se ve de la siguiente manera: 

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

      • Chrome 44 y versiones posteriores
      • tab

        Tab

        Chrome 44 y versiones posteriores

        Los detalles de la pestaña en la que se produjo el clic Este parámetro no está presente para apps de plataforma.

  • callback

    Función opcional

    El parámetro callback se ve de la siguiente manera: 

    ()=>void

Devuelve

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onClicked

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

Se activa cuando se hace clic en un elemento del menú contextual.

Parámetros