Descripción
Usa la API de chrome.action
para controlar el ícono de la extensión en la barra de herramientas de Google Chrome.
Disponibilidad
Manifest
Para usar la API de chrome.action
, especifica un "manifest_version"
de 3
y la clave "action"
en tu archivo de manifiesto.
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
La clave "action"
(junto con sus elementos secundarios) es opcional. Cuando no está incluida, la extensión aún se muestra en la barra de herramientas para proporcionar acceso al menú de la extensión. Por este motivo, te recomendamos que siempre incluyas al menos las claves "action"
y "default_icon"
.
Conceptos y uso
Partes de la IU
Ícono
El ícono es la imagen principal en la barra de herramientas de tu extensión y se establece con la clave "default_icon"
en la clave "action"
de tu manifiesto. Los íconos deben tener 16 píxeles independientes del dispositivo (DIP) de ancho y alto.
La clave "default_icon"
es un diccionario de tamaños para las rutas de acceso de imágenes. Chrome usa estos íconos
para elegir qué escala de imagen usar. Si no se encuentra una coincidencia exacta, Chrome selecciona la opción más cercana disponible y la escala para que se ajuste a la imagen, lo que podría afectar la calidad de la imagen.
Debido a que los dispositivos con factores de escala menos comunes, como 1.5x o 1.2x, son cada vez más comunes, te recomendamos que proporciones varios tamaños para tus íconos. De esta manera,
la extensión también estará preparada para el futuro frente a posibles cambios en el tamaño de visualización del ícono. Sin embargo, si solo proporcionas un tamaño único, la clave "default_icon"
también se puede establecer en una string con la ruta de acceso a un solo ícono en lugar de a un diccionario.
También puedes llamar a action.setIcon()
para configurar el ícono de tu extensión de manera programática.
Para ello, especifica una ruta de imagen diferente o proporciona un ícono generado de forma dinámica con el elemento de lienzo
HTML. Si lo configuras desde un service worker de extensión, puedes usar la API de lienzo
fuera de pantalla.
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });
En el caso de las extensiones empaquetadas (instaladas desde un archivo .crx), las imágenes pueden estar en la mayoría de los formatos que el motor de renderización de Blink puede mostrar, incluidos PNG, JPEG, BMP, ICO y otros. No se admite SVG. Las extensiones sin empaquetar deben usar imágenes en formato PNG.
Información sobre la herramienta (título)
La información sobre la herramienta, o título, aparece cuando el usuario mantiene el puntero del mouse sobre el ícono de la extensión en la barra de herramientas. También se incluye en el texto accesible que dicen los lectores de pantalla cuando se enfoca el botón.
La información sobre la herramienta predeterminada se establece con el campo "default_title"
de la clave "action"
en manifest.json
.
También puedes configurarlo de manera programática llamando a action.setTitle()
.
Insignia
De manera opcional, las acciones pueden mostrar una "insignia", un poco de texto sobre el ícono. Esto te permite actualizar la acción para que muestre una pequeña cantidad de información sobre el estado de la extensión, como un contador. La insignia tiene un componente de texto y un color de fondo. Debido a que el espacio es limitado, recomendamos que el texto de la insignia tenga cuatro caracteres o menos.
Para crear una insignia, configúrala de manera programática llamando a action.setBadgeBackgroundColor()
y action.setBadgeText()
. El manifiesto no incluye una configuración de insignia predeterminada. Los valores de color de la insignia pueden ser un array de cuatro números enteros entre 0 y 255 que componen el color RGBA de la insignia o una string con un valor de color CSS.
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Ventana emergente
Se muestra la ventana emergente de una acción cuando el usuario hace clic en el botón de acción de la extensión, en la barra de herramientas. La ventana emergente puede incluir cualquier contenido HTML que desees y su tamaño se ajustará automáticamente para adaptarse a su contenido. El tamaño de la ventana emergente debe ser de entre 25 x 25 y 800 x 600 píxeles.
Inicialmente, la propiedad "default_popup"
configura la ventana emergente en la clave "action"
del archivo manifest.json
. Si está presente, esta propiedad debe apuntar a una ruta de acceso relativa dentro del directorio de la
extensión. También se puede actualizar de forma dinámica para que apunte a una ruta relativa diferente con el método action.setPopup()
.
Casos de uso
Estado por pestaña
Las acciones de las extensiones pueden tener diferentes estados para cada pestaña. Para establecer un valor para una pestaña individual, usa la propiedad tabId
en los métodos de configuración de la API de action
. Por ejemplo, para configurar el texto de la insignia en una pestaña específica, haz lo siguiente:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Si omites la propiedad tabId
, el parámetro de configuración se trata como una configuración global. La configuración específica de la pestaña tiene prioridad sobre la configuración global.
Estado habilitado
De forma predeterminada, las acciones de la barra de herramientas están habilitadas (en las que se puede hacer clic) en todas las pestañas. Puedes controlar esto con los métodos action.enable()
y action.disable()
. Esto solo afecta si el evento de ventana emergente (si existe) o
action.onClicked
se envía a tu extensión; no afecta la presencia de la acción
en la barra de herramientas.
Ejemplos
En los siguientes ejemplos, se muestran algunas formas comunes en que se utilizan las acciones en las extensiones. Para probar esta API, instala el ejemplo de la API de Action del repositorio chrome-extension-samples.
Mostrar una ventana emergente
Es común que una extensión muestre una ventana emergente cuando el usuario hace clic en la acción de la extensión. Para
implementar esto en tu propia extensión, declara la ventana emergente en tu manifest.json
y especifica el
contenido que Chrome debe mostrar en ella.
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
Incorpora una secuencia de comandos de contenido al hacer clic
Un patrón común para las extensiones es exponer su función principal con la acción de la extensión. En el siguiente ejemplo, se demuestra este patrón. Cuando el usuario hace clic en la acción, la extensión inserta una secuencia de comandos de contenido en la página actual. Luego, la secuencia de comandos del contenido muestra una alerta para verificar que todo funcionó como se esperaba.
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
Emula acciones con declarativeContent
En este ejemplo, se muestra cómo la lógica en segundo plano de una extensión puede (a) inhabilitar una acción de forma predeterminada y (b) usar declarativeContent para habilitar la acción en sitios específicos.
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
Tipos
OpenPopupOptions
Propiedades
-
windowId
número opcional
El ID de la ventana en la que se abrirá la ventana emergente de acción. Si no se especifica, el valor predeterminado es la ventana que está activa en este momento.
TabDetails
Propiedades
-
tabId
número opcional
El ID de la pestaña para consultar el estado. Si no se especifica una pestaña, se muestra el estado no específico de pestaña.
UserSettings
Es el conjunto de parámetros de configuración especificados por el usuario relacionados con la acción de una extensión.
Propiedades
-
isOnToolbar
boolean
Si el ícono de acción de la extensión es visible en la barra de herramientas de nivel superior de las ventanas del navegador (es decir, si el usuario "fijó" la extensión)
Métodos
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
Inhabilita la acción para una pestaña.
Parámetros
-
tabId
número opcional
El ID de la pestaña para la que deseas modificar la acción.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Habilita la acción para una pestaña. Las acciones están habilitadas de forma predeterminada.
Parámetros
-
tabId
número opcional
El ID de la pestaña para la que deseas modificar la acción.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Obtiene el color de fondo de la acción.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: ColorArray) => void
-
resultado
-
Devuelve
-
Promise<browserAction.ColorArray>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Obtiene el texto de la insignia de la acción. Si no se especifica ninguna pestaña, se mostrará el texto de la insignia que no es específico de pestaña. Si displayActionCountAsBadgeText está habilitada, se mostrará un texto de marcador de posición, a menos que esté presente el permiso declarativeNetRequestFeedback o que se proporcione texto de insignia específico de la pestaña.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: string) => void
-
resultado
cadena
-
Devuelve
-
Promesa<string>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Obtiene el color del texto de la acción.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: ColorArray) => void
-
resultado
-
Devuelve
-
Promise<browserAction.ColorArray>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Obtiene el documento HTML configurado como ventana emergente para esta acción.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: string) => void
-
resultado
cadena
-
Devuelve
-
Promesa<string>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Obtiene el título de la acción.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: string) => void
-
resultado
cadena
-
Devuelve
-
Promesa<string>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Muestra la configuración especificada por el usuario relacionada con la acción de una extensión.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(userSettings: UserSettings) => void
-
userSettings
-
Devuelve
-
Promise<UserSettings>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Indica si la acción de extensión está habilitada para una pestaña (o de forma global si no se proporciona una tabId
). Las acciones que se habilitan solo con declarativeContent
siempre muestran un valor falso.
Parámetros
-
tabId
número opcional
El ID de la pestaña para la que deseas comprobar el estado habilitado.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(isEnabled: boolean) => void
-
isEnabled
boolean
Es verdadero si la acción de extensión está habilitada.
-
Devuelve
-
Promise<boolean>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Abre la ventana emergente de la extensión.
Parámetros
-
Opciones
OpenPopupOptions opcional
Especifica las opciones para abrir la ventana emergente.
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Establece el color de fondo para la insignia.
Parámetros
-
detalles
objeto
-
color
string | ColorArray
Es un array de cuatro números enteros dentro del rango [0,255] que componen el color RGBA de la insignia. Por ejemplo, el rojo opaco es
[255, 0, 0, 255]
. También puede ser una string con un valor de CSS, en el que el rojo opaco es#FF0000
o#F00
. -
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Establece el texto de la insignia de la acción. La insignia aparece sobre el ícono.
Parámetros
-
detalles
objeto
-
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
text
cadena opcional
Se puede pasar cualquier cantidad de caracteres, pero solo pueden caber aproximadamente cuatro en el espacio. Si se pasa una cadena vacía (
''
), el texto de la insignia se borra. Si se especificatabId
ytext
es nulo, se borra el texto de la pestaña especificada y se establece de forma predeterminada el texto de la insignia global.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
Establece el color del texto para la insignia.
Parámetros
-
detalles
objeto
-
color
string | ColorArray
Es un array de cuatro números enteros dentro del rango [0,255] que componen el color RGBA de la insignia. Por ejemplo, el rojo opaco es
[255, 0, 0, 255]
. También puede ser una string con un valor de CSS, en el que el rojo opaco es#FF0000
o#F00
. Si no estableces este valor, se elegirá automáticamente un color que contrastará con el color de fondo de la insignia, de modo que el texto sea visible. Los colores con valores alfa equivalentes a 0 no se establecerán y mostrarán un error. -
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
Establece el ícono para la acción. El ícono se puede especificar como la ruta de acceso a un archivo de imagen o como los datos de píxeles de un elemento del lienzo, o como un diccionario de cualquiera de ellos. Se debe especificar la propiedad path o imageData.
Parámetros
-
detalles
objeto
-
imageData
ImageData | objeto opcional
Un objeto ImageData o un diccionario {size -> ImageData} que representa el ícono que se configurará. Si el ícono se especifica como un diccionario, se elige la imagen real que se usará según la densidad de píxeles de la pantalla. Si la cantidad de píxeles de imagen que caben en una unidad de espacio de pantalla es igual a
scale
, se seleccionará una imagen con el tamañoscale
* n, donde n es el tamaño del ícono en la IU. Se debe especificar al menos una imagen. Ten en cuenta que “details.imageData = foo” es equivalente a “details.imageData = {'16': foo}'. -
ruta de acceso
cadena | objeto opcional
Una ruta de acceso de imagen relativa o un diccionario {size -> relativo a la ruta de la imagen} que apunta al ícono que se debe configurar. Si el ícono se especifica como un diccionario, se elige la imagen real que se usará según la densidad de píxeles de la pantalla. Si la cantidad de píxeles de imagen que caben en una unidad de espacio de pantalla es igual a
scale
, se seleccionará una imagen con el tamañoscale
* n, donde n es el tamaño del ícono en la IU. Se debe especificar al menos una imagen. Ten en cuenta que “details.path = foo” es equivalente a “details.path = {'16': foo}'. -
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
Configura el documento HTML que se abrirá como una ventana emergente cuando el usuario haga clic en el ícono de la acción.
Parámetros
-
detalles
objeto
-
ventana emergente
cadena
La ruta de acceso relativa al archivo HTML que se mostrará en una ventana emergente. Si se establece como la string vacía (
''
), no se muestra ninguna ventana emergente. -
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Establece el título de la acción. Esto aparece en el cuadro de información.
Parámetros
-
detalles
objeto
-
tabId
número opcional
Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.
-
title
cadena
Es la cadena que la acción debe mostrar al desplazar el mouse sobre ella.
-
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar 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.action.onClicked.addListener(
callback: function,
)
Se activa cuando se hace clic en un ícono de acción. Este evento no se activará si la acción tiene una ventana emergente.