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
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 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.
Manifest
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 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"
},
...
}
Ejemplos
Para probar esta API, instala el ejemplo de la API de contextoMenus del repositorio chrome-extension-samples.
Tipos
ContextType
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
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 atributosrc
de las etiquetasimg
,audio
yvideo
, y en el atributohref
de las etiquetasa
. -
title
cadena opcional
El texto que se mostrará en el elemento. Es obligatorio, a menos que
type
seaseparator
. Cuando el contexto seaselection
, 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) => {...}
-
info
Información sobre el elemento en el que se hizo clic y el contexto donde se hizo el clic.
-
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
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 posterioresEl 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.
-
cadena | número
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
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
número | cadena
El ID del elemento recién creado.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Elimina un elemento del menú contextual.
Parámetros
-
cadena | número
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
removeAll()
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
Actualiza un elemento de menú contextual creado anteriormente.
Parámetros
-
id
cadena | número
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
-
title
cadena opcional
-
Tipo
ItemType opcional
-
visible
booleano opcional
Chrome 62 y versiones posterioresIndica 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) => {...}
-
infoChrome 44 y versiones posteriores
-
tabChrome 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
Eventos
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
Se activa cuando se hace clic en un elemento del menú contextual.
Parámetros
-
callback
la función
El parámetro
callback
se ve de la siguiente manera:(info: OnClickData, tab?: tabs.Tab) => void
-
info
-
tab
tabs.Tab opcional
-