Descripción
Usa las acciones del navegador para colocar íconos en la barra de herramientas principal de Google Chrome, a la derecha de la barra de direcciones. Además de su ícono, una acción del navegador puede tener una información sobre la herramienta, una insignia y una ventana emergente.
Disponibilidad
En la siguiente imagen, el cuadrado multicolor que se encuentra a la derecha de la barra de direcciones es el ícono de una acción del navegador. Hay una ventana emergente debajo del ícono.
Si deseas crear un ícono que no siempre esté activo, usa una acción de página en lugar de una acción del navegador.
Manifest
Registra la acción del navegador en el manifiesto de extensión de la siguiente manera:
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Puedes proporcionar un ícono de cualquier tamaño para usar en Chrome. Chrome seleccionará el más cercano y lo escalará al tamaño adecuado para llenar el espacio de 16 dip. Sin embargo, si no se proporciona el tamaño exacto, este escalamiento puede hacer que el ícono pierda detalles o se vea difuso.
Dado 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. Esto también garantiza que, si alguna vez se cambia el tamaño de visualización del ícono, no tengas que trabajar más para proporcionar diferentes íconos.
Aún se admite la sintaxis antigua para registrar el ícono predeterminado:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
Partes de la IU
Una acción del navegador puede tener un ícono, una información sobre la herramienta, una insignia y una ventana emergente.
Ícono
Los íconos de acción del navegador en Chrome tienen 16 caídas (píxeles independientes del dispositivo) de ancho y alto. Los íconos más grandes se pueden cambiar de tamaño para ajustarlos, pero para obtener mejores resultados, usa un ícono cuadrado de 16 posiciones.
Puedes configurar el ícono de dos maneras: con una imagen estática o con el elemento de lienzo de HTML5. El uso de imágenes estáticas es más fácil para las aplicaciones simples, pero puedes crear IUs más dinámicas, como animaciones más fluidas, con el elemento lienzo.
Las imágenes estáticas pueden tener cualquier formato que pueda mostrar WebKit, incluidos BMP, GIF, ICO, JPEG o PNG. En el caso de las extensiones sin empaquetar, las imágenes deben estar en formato PNG.
Para configurar el ícono, usa el campo default_icon de default_icon en el manifiesto o llama al método browserAction.setIcon
.
Para mostrar correctamente el ícono cuando la densidad de píxeles de la pantalla (proporción size_in_pixel / size_in_dip
) sea diferente de 1, se puede definir el ícono como un conjunto de imágenes con diferentes tamaños. La imagen real que se mostrará se seleccionará del conjunto para que se ajuste mejor al tamaño de píxeles de 16 dip. El conjunto de íconos puede contener cualquier especificación de tamaño de ícono, y Chrome seleccionará la más adecuada.
Información sobre la herramienta
Para configurar la información sobre la herramienta, usa el campo default_title de default_title en el manifiesto o llama al método browserAction.setTitle
. Puedes especificar cadenas específicas de la configuración regional en el campo default_title. Consulta Internacionalización para obtener más información.
Insignia
De manera opcional, las acciones del navegador pueden mostrar una insignia, que es un fragmento de texto superpuesto sobre el ícono. Las insignias facilitan la actualización de la acción del navegador para mostrar una pequeña cantidad de información sobre el estado de la extensión.
Como la insignia tiene espacio limitado, debe tener 4 caracteres o menos.
Establece el texto y el color de la insignia con browserAction.setBadgeText
y browserAction.setBadgeBackgroundColor
, respectivamente.
Ventana emergente
Si una acción del navegador tiene una ventana emergente, esta aparecerá cuando el usuario haga clic en el ícono de la extensión. La ventana emergente puede incluir cualquier contenido HTML que desees y su tamaño se ajusta automáticamente para adaptarse a su contenido. La ventana emergente no puede tener un tamaño inferior a 25 x 25 ni a un tamaño superior a 800 x 600.
Para agregar una ventana emergente a la acción de tu navegador, crea un archivo HTML con su contenido. Especifica el archivo HTML en el campo default_popup de default_popup en el manifiesto o llama al método browserAction.setPopup
.
Sugerencia
Para obtener el mejor impacto visual, sigue estos lineamientos:
- Usa las acciones del navegador para las funciones que tengan sentido en la mayoría de las páginas.
- No uses acciones del navegador para funciones que solo funcionan en unas pocas páginas. En su lugar, usa acciones de página.
- Usa íconos grandes y coloridos que aprovechen al máximo el espacio de 16 × 16. Los íconos de acción del navegador deben parecer un poco más grandes y más pesados que los íconos de acciones de página.
- No intentes imitar el ícono monocromático de menú monocromático de Google Chrome. Eso no funciona bien con los temas y, de todos modos, las extensiones deberían destacarse un poco.
- Usa la transparencia alfa para agregar bordes suaves a tu ícono. Como muchas personas usan temas, tu ícono debería verse bien con una variedad de colores de fondo.
- No animes tu ícono constantemente. Eso es muy molesto.
Ejemplos
Puedes encontrar ejemplos simples del uso de acciones del navegador en el directorio examples/api/browserAction. Para ver otros ejemplos y obtener ayuda con la visualización del código fuente, consulta Muestras.
Tipos
ColorArray
Tipo
[número, número, número, número]
ImageDataType
Datos de píxeles para una imagen. Debe ser un objeto ImageData, por ejemplo, de un elemento canvas
.
Tipo
ImageData
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.
Métodos
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
Inhabilita la acción del navegador para una pestaña.
Parámetros
-
tabId
número opcional
El ID de la pestaña para la que se modifica la acción del navegador.
-
callback
Función opcional
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
Habilita la acción del navegador para una pestaña. La configuración predeterminada es habilitada.
Parámetros
-
tabId
número opcional
El ID de la pestaña para la que se modifica la acción del navegador.
-
callback
Función opcional
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Obtiene el color de fondo de la acción del navegador.
Parámetros
-
detalles
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(result: ColorArray) => void
-
resultado
-
Devuelve
-
Promise<ColorArray>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
Obtiene el texto de la insignia de la acción del navegador. Si no se especifica ninguna pestaña, se mostrará el texto de la insignia que no es específico de 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>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Obtiene el documento HTML que se configuró como la ventana emergente para esta acción del navegador.
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>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Obtiene el título de la acción del navegador.
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>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Establece el color de fondo para la insignia.
Parámetros
-
detalles
objeto
-
color
string | ColorArray
Un array de cuatro números enteros entre 0 y 255 que componen el color RGBA de la insignia. También puede ser una cadena con un valor de color hexadecimal CSS, por ejemplo,
#FF0000
o#F00
(rojo). Renderiza colores con plena opacidad. -
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
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
Establece el texto de la insignia para la acción del navegador. 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
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
Establece el ícono para la acción del navegador. Se puede especificar el ícono como la ruta de acceso a un archivo de imagen, como los datos de píxeles de un elemento del lienzo o como un diccionario de uno 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 un ícono que se configurará. Si el ícono se especifica como un diccionario, la imagen que se usa se elige 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 -> image path} relativa que apunte a un ícono que se configurará. Si el ícono se especifica como un diccionario, la imagen que se usa se elige 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 116 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setPopup()
chrome.browserAction.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 acción del navegador.
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
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
Establece el título de la acción del navegador. Este título aparece en la información sobre la herramienta.
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 del navegador debe mostrar al desplazar el mouse sobre ella.
-
-
callback
Función opcional
Chrome 67 y versiones posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 88 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
Eventos
onClicked
chrome.browserAction.onClicked.addListener(
callback: function,
)
Se activa cuando se hace clic en un ícono de acción del navegador. No se activa si la acción del navegador tiene una ventana emergente.