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 aplicarán los elementos que agregues al 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 que se muestre 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 con file:// o chrome://. Para controlar en qué documentos pueden aparecer tus elementos, especifica la documentUrlPatterns cuando llames a los métodos create() o update().

Puedes crear tantos elementos de menú contextual como necesites, pero si se agrega más de un elemento de tu extensión visibles a la vez, Google Chrome las contrae automáticamente en un único menú superior.

Ejemplos

Para probar esta API, instala el ejemplo de la API de contextoMenus desde chrome-extension-samples en un repositorio de confianza.

Tipos

ContextType

Chrome 44 y versiones posteriores

Los diferentes contextos en los que puede aparecer un menú. Especificar “all” equivale a la combinación de todos los demás contextos excepto "launcher". El "selector" solo es compatible con apps y se usa para agregar elementos de menú al menú contextual que aparece al hacer clic en el ícono de la app en el selector, la barra de tareas, el conector, etcétera. Las diferentes plataformas pueden imponer limitaciones respecto de lo que realmente es compatible con un menú contextual de selector.

Enum

“todos”

“página”

“frame”

“selección”

“vínculo”

“editable”

“imagen”

“video”

“audio”

“Selector”

"browser_action"

"page_action"

“action”

CreateProperties

Chrome 123 y versiones posteriores

Propiedades del nuevo elemento de menú contextual.

Propiedades

  • activado

    booleano opcional

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

  • contextos

    [ContextType, ...ContextType[]] opcional

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

  • documentUrlPatterns

    string[] opcional

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

  • habilitado

    booleano opcional

    Si este elemento del menú contextual está habilitado o inhabilitado. La configuración predeterminada es true.

  • id

    string opcional

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

  • parentId

    string | número opcional

    Es 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

    Al igual que 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

    string opcional

    El texto que se mostrará en el elemento. esto 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 para la selección es "Traducir 'genial' a Pig Latin".

  • tipo

    ItemType opcional

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

  • visible

    booleano opcional

    Indica si el elemento se muestra en el menú.

  • onclick

    void optional

    Una función a la que se vuelve a llamar cuando se hace clic en el elemento de menú. Esta opción no está disponible dentro de 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

      OnClickData

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

    • tab

      Tab

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

ItemType

Chrome 44 y versiones posteriores

Es el tipo de elemento de menú.

Enum

“normal”

"casilla de verificación"

“radio”

“separator”

OnClickData

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

Propiedades

  • activado

    booleano opcional

    Marca que indica el estado de una casilla de verificación o un elemento de selección después de que se hace clic en ellos.

  • modificable

    boolean

    Marca que indica si el elemento se puede editar (entrada de texto, área de texto, etc.).

  • frameId

    número opcional

    Chrome 51 y versiones posteriores

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

  • frameUrl

    string opcional

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

  • linkUrl

    string opcional

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

  • mediaType

    string opcional

    Los valores de "image", "video" o "audio" si el menú contextual se activó en uno de estos tipos de elementos.

  • menuItemId

    string | número

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

  • pageUrl

    string opcional

    Es 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 selector.

  • parentMenuItemId

    string | número opcional

    El ID superior, si lo hay, del elemento en el que se hizo clic.

  • selectionText

    string opcional

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

  • srcUrl

    string opcional

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

  • wasChecked

    booleano opcional

    Marca que indica el estado de una casilla de verificación o un elemento de selección antes de que se haga clic en ellos.

Propiedades

ACTION_MENU_TOP_LEVEL_LIMIT

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

Muestra

  • número | cadena

    El ID del elemento recién creado.

remove()

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

Quita un elemento del menú contextual.

Parámetros

  • menuItemId

    string | número

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

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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

Muestra

  • Promesa<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 | número

    El ID del elemento que se actualizará.

  • updateProperties

    objeto

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

    • activado

      booleano opcional

    • contextos

      [ContextType, ...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • habilitado

      booleano opcional

    • parentId

      string | número opcional

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

    • targetUrlPatterns

      string[] opcional

    • título

      string opcional

    • tipo

      ItemType opcional

    • visible

      booleano opcional

      Chrome 62 y versiones posteriores

      Indica si el elemento se muestra en el menú.

    • onclick

      void optional

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

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

      • información

        OnClickData

        Chrome 44 y versiones posteriores
      • tab

        Tab

        Chrome 44 y versiones posteriores

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

  • callback

    función opcional

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

    () => void

Muestra

  • Promesa<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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