browser.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 adiciones del menú contextual, como imágenes, hipervínculos y páginas.

Permisos

contextMenus

Debes declarar el permiso "contextMenus" en el manifiesto de tu extensión para usar la API. 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 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 tantos elementos de menú contextual como necesites, pero si hay más de uno de tu extensión visible a la vez, Google Chrome los contrae automáticamente en un solo menú parental.

La mayor parte de esta página contiene información de referencia para los miembros de esta API. Para obtener instrucciones sobre cómo usar la API, consulta Cómo compilar un menú contextual.

Ejemplos

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

Tipos

ContextType

Chrome 44 y versiones posteriores browser.* desde Chrome 148

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" y "tab". Solo las apps admiten el contexto "launcher", que se usa para agregar elementos al menú contextual que aparece cuando se hace clic en el ícono de la app en el selector, la barra de tareas, el dock, etcétera. Es posible que algunas plataformas limiten lo que se admite en un menú contextual de selector.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
Se aplica al menú contextual de la acción de la extensión (su ícono de la barra de herramientas).

"tab"
Se aplica al menú contextual de una pestaña en la tira de pestañas.

CreateProperties

Chrome 123 y versiones posteriores browser.* desde Chrome 148

Son las propiedades del nuevo elemento del menú contextual.

Propiedades

  • elemento marcado

    booleano opcional

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

  • contextos

    [ContextType, ...ContextType[]] opcional

    Es la 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 solo a los documentos o marcos cuya URL coincida con uno de los patrones dados. Para obtener detalles sobre los formatos de patrones, consulta Patrones de coincidencia.

  • habilitado

    booleano opcional

    Indica 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. Obligatorio para las páginas de eventos. No puede ser igual a otro ID de esta extensión.

  • parentId

    string | number opcional

    Es el ID de un elemento de menú superior, lo que convierte al elemento en un elemento secundario de un elemento agregado anteriormente.

  • targetUrlPatterns

    string[] opcional

    Al igual que documentUrlPatterns, filtra según el atributo src de las etiquetas img, audio y video, y el atributo href de las etiquetas a.

  • título

    string opcional

    Es 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' al latín de los cerdos" y el usuario selecciona la palabra "genial", el elemento del menú contextual para la selección es "Traducir 'genial' al latín de los cerdos".

  • tipo

    ItemType opcional

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

  • visible

    booleano opcional

    Indica si el elemento es visible en el menú.

  • onclick

    void optional

    Es una función a la que se vuelve a llamar cuando se hace clic en el elemento de menú. Esto 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 produjo el clic.

    • tabulación

      Tab

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

ItemType

Chrome 44 y versiones posteriores browser.* desde Chrome 148

Es el tipo de elemento de menú.

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

Propiedades

  • elemento marcado

    booleano opcional

    Es una marca que indica el estado de una casilla de verificación o un elemento de selección después de hacer clic en él.

  • editable

    booleano

    Es un indicador que señala si el elemento se puede editar (entrada de texto, área de texto, etcétera).

  • frameId

    number opcional

    Chrome 51 y versiones posteriores browser.* desde Chrome 148

    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, la URL a la que dirige.

  • mediaType

    string opcional

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

  • menuItemId

    string | number

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

  • parentMenuItemId

    string | number opcional

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

  • selectionText

    string opcional

    Es el texto de la selección de contexto, si lo hay.

  • srcUrl

    string opcional

    Estará presente para los elementos con una URL "src".

  • wasChecked

    booleano opcional

    Es un indicador que muestra el estado de una casilla de verificación o 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 al menú contextual de una acción de extensión. Se ignorarán los elementos que superen este límite.

Valor

6

Métodos

create()

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

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 se encontrarán en runtime.lastError.

Parámetros

  • createProperties

    CreateProperties

  • callback

    función opcional

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

    () => void

Muestra

  • number | string

    Es el ID del elemento recién creado.

remove()

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

Quita un elemento del menú contextual.

Parámetros

  • menuItemId

    string | number

    Es el ID del elemento del menú contextual que se quitará.

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores browser.* desde Chrome 148

    Se resuelve cuando se quita el menú contextual.

removeAll()

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

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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores browser.* desde Chrome 148

    Se resuelve cuando se completa la eliminación.

update()

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

Actualiza un elemento de menú contextual creado anteriormente.

Parámetros

  • id

    string | number

    Es el ID del elemento que se actualizará.

  • updateProperties

    objeto

    Son 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

      string | number opcional

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

    • targetUrlPatterns

      string[] opcional

    • título

      string opcional

    • tipo

      ItemType opcional

    • visible

      booleano opcional

      Chrome 62 y versiones posteriores browser.* desde Chrome 148

      Indica si el elemento es visible 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 browser.* desde Chrome 148
      • tabulación

        Tab

        Chrome 44 y versiones posteriores browser.* desde Chrome 148

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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores browser.* desde Chrome 148

    Se resuelve cuando se actualiza el menú contextual.

Eventos

onClicked

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

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

Parámetros