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
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 llamas 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.
Manifiesto
Debes declarar los "contextMenus" permiso 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"
},
...
}
Ejemplos
Para probar esta API, instala el ejemplo de la API de contextoMenus desde chrome-extension-samples en un repositorio de confianza.
Tipos
ContextType
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
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 atributosrc
de las etiquetasimg
,audio
yvideo
, y en el atributohref
de las etiquetasa
. -
título
string opcional
El texto que se mostrará en el elemento. esto 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 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
Información sobre el elemento en el que se hizo clic y el contexto en el que se hizo clic.
-
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
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 posterioresEs 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.
-
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
-
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()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
Quita un elemento del menú contextual.
Parámetros
-
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 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
Muestra
-
Promesa<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
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 posterioresIndica 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ónChrome 44 y versiones posteriores
-
tabChrome 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 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
función
El parámetro
callback
se ve de la siguiente manera:(info: OnClickData, tab?: tabs.Tab) => void
-
información
-
tab
tabs.Tab opcional
-