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 tus adiciones al 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 x 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 se muestra más de uno de tu extensión a la vez, Google Chrome los contrae automáticamente en un solo menú principal.

Ejemplos

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

Tipos

ContextType

Chrome 44 y versiones posteriores

Son 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 contexto "launcher" 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 dock, 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 los documentos o los marcos cuya URL coincida con uno de los patrones proporcionados. 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

    cadena 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

    cadena | número opcional

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

  • targetUrlPatterns

    string[] opcional

    De manera similar a documentUrlPatterns, filtra según el atributo src de las etiquetas img, audio y video, y 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 es selection, usa %s dentro de la cadena para mostrar el texto seleccionado. Por ejemplo, si el valor de este parámetro es "Traduce "%s" al latín de cerdo" y el usuario selecciona la palabra "cool", el elemento del menú contextual para la selección es "Traduce "cool" al latín de cerdo".

  • tipo

    ItemType opcional

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

  • visible

    booleano opcional

    Indica si el elemento está visible en el menú.

  • onclick

    void optional

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

      Es información sobre el elemento en el que se hizo clic y el contexto en el que se produjo el clic.

    • tab

      Tab

      Son los detalles de la pestaña en la que se hizo 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 botón 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é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

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

  • mediaType

    cadena opcional

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

  • menuItemId

    cadena | número

    Es el ID del elemento de 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

    Es el ID principal, si existe, 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 de "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 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á cualquier elemento que supere este límite.

Valor

6

Métodos

create()

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

Crea un elemento nuevo del 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()

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

Quita un elemento del menú contextual.

Parámetros

  • menuItemId

    cadena | número

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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

removeAll()

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

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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

update()

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

Actualiza un elemento de menú contextual creado anteriormente.

Parámetros

  • id

    cadena | número

    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.

    • activado

      booleano opcional

    • contextos

      [ContextType, ...ContextType[]] opcional

    • documentUrlPatterns

      string[] opcional

    • habilitado

      booleano opcional

    • parentId

      cadena | número opcional

      ID del elemento que se convertirá en el elemento principal de este elemento. Nota: No puedes establecer que un elemento se convierta en 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 está 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
      • tab

        Tab

        Chrome 44 y versiones posteriores

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

Muestra

  • Promise<void>

    Chrome 123 y versiones posteriores

Eventos

onClicked

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

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

Parámetros