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 opciones 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 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 más de uno de tu extensión es visible a la vez, Google Chrome los contrae automáticamente en un solo menú superior.

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

Los diferentes contextos en los que puede aparecer un menú. Especificar "todos" equivale a la combinación de todos los demás contextos, excepto "iniciador". El contexto de "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, la estación de carga, etcétera. Las diferentes plataformas pueden imponer limitaciones sobre lo que realmente se admite en un menú contextual del selector.

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 y versiones posteriores

Son las propiedades del nuevo elemento del menú contextual.

Propiedades

  • activado

    booleano opcional

    Es el estado inicial de una casilla de verificación o un botón de selección: true para seleccionado y 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 documentos o marcos cuya URL coincida con uno de los patrones determinados. Para obtener más información 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

    cadena opcional

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

  • parentId

    cadena | número opcional

    Es el ID de un elemento de menú superior, lo que hace que el elemento sea 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

    cadena 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' a Pig Latin" y el usuario selecciona la palabra "cool", el elemento del menú contextual para la selección es "Traducir 'cool' 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 es visible en el menú.

  • onclick

    void optional

    Es una función a la que se le llama 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.

    • tab

      Tab

      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

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

  • activado

    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 una marca que indica si el elemento es editable (entrada de texto, textarea, etc.).

  • 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

    Es la URL del marco del elemento en el que 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

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

  • menuItemId

    cadena | número

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

  • pageUrl

    cadena 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

    cadena | número opcional

    El ID superior, si corresponde, del elemento en el que se hizo clic

  • selectionText

    cadena opcional

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

  • srcUrl

    cadena opcional

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

  • wasChecked

    booleano opcional

    Es una marca que indica el estado de una casilla de verificación o un elemento de selección antes de hacer 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 acción de extensión. Se ignorarán los elementos que superen 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 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

  • número | cadena

    Es 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

    cadena | número

    Es 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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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 con anterioridad.

Parámetros

  • id

    cadena | número

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

    • activado

      booleano opcional

    • contextos

      [ContextType, ...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • habilitado

      booleano opcional

    • parentId

      cadena | número opcional

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

    • 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) => {...}

      • 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 produjo el clic Este parámetro no está presente en las apps de la plataforma.

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

    Las promesas son compatibles con el manifiesto V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para la 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