chrome.browserAction

refresh date: 2026-09-25 robots: noindex

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

≤ MV2

En la siguiente figura, el cuadrado multicolor a la derecha de la barra de direcciones es el ícono de una acción del navegador. Debajo del ícono, hay una ventana emergente.

Si quieres crear un ícono que no siempre esté activo, usa una acción de página en lugar de una acción del navegador.

Manifiesto

Registra la acción del navegador en el manifiesto de la 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 usarlo en Chrome, y 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 borroso.

Dado que los dispositivos con factores de escala menos comunes, como 1.5x o 1.2x, son cada vez más frecuentes, te recomendamos que proporciones varios tamaños para tus íconos. Esto también garantiza que, si alguna vez cambia el tamaño de visualización del ícono, no tendrás que hacer más trabajo para proporcionar íconos diferentes.

Aún se admite la sintaxis anterior 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 dips (píxeles independientes del dispositivo) de ancho y alto. Los íconos más grandes se ajustan para que quepan, pero, para obtener mejores resultados, usa un ícono cuadrado de 16 dip.

Puedes configurar el ícono de dos maneras: con una imagen estática o con el elemento canvas de HTML5. Usar imágenes estáticas es más fácil para las aplicaciones simples, pero puedes crear IU más dinámicas, como animaciones fluidas, con el elemento canvas.

Las imágenes estáticas pueden estar en cualquier formato que WebKit pueda mostrar, incluidos BMP, GIF, ICO, JPEG o PNG. En el caso de las extensiones sin empaquetar, las imágenes deben estar en formato PNG.

Para establecer el ícono, usa el campo default_icon de browser_action 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) es diferente de 1, el ícono se puede definir 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íxel de 16 dip. El conjunto de íconos puede contener especificaciones de íconos de cualquier tamaño, y Chrome seleccionará el más adecuado.

Información sobre la herramienta

Para establecer la información sobre la herramienta, usa el campo default_title de browser_action en el manifiesto o llama al método browserAction.setTitle. Puedes especificar cadenas específicas de la configuración regional para el campo default_title. Consulta Internacionalización para obtener más detalles.

Insignia

Las acciones del navegador pueden mostrar opcionalmente una insignia, un poco de texto que se superpone al í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.

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 contener cualquier contenido HTML que desees y su tamaño se ajusta automáticamente para adaptarse a su contenido. La ventana emergente no puede ser menor que 25 × 25 ni mayor que 800 × 600.

Para agregar una ventana emergente a la acción del navegador, crea un archivo HTML con el contenido de la ventana emergente. Especifica el archivo HTML en el campo default_popup de browser_action en el manifiesto o llama al método browserAction.setPopup.

Sugerencias

Para lograr el mejor impacto visual, sigue estos lineamientos:

  • Sí usa 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 tienen sentido en unas pocas páginas. En su lugar, usa acciones de página.
  • Sí usa íconos grandes y coloridos que aprovechen al máximo el espacio de 16 x 16 dp. Los íconos de acción del navegador deberían verse un poco más grandes y pesados que los íconos de acción de la página.
  • No intentes imitar el ícono monocromático del menú de Google Chrome. Eso no funciona bien con los temas y, de todos modos, las extensiones deberían destacarse un poco.
  • Sí usa la transparencia alfa para agregar bordes suaves a tu ícono. Como muchas personas usan temas, tu ícono debería verse bien en una variedad de colores de fondo.
  • No animes el ícono de forma constante. Eso es molesto.

Ejemplos

Puedes encontrar ejemplos sencillos de uso de acciones del navegador en el directorio examples/api/browserAction. Para ver otros ejemplos y obtener ayuda para ver el código fuente, consulta Muestras.

Tipos

TabDetails

Chrome 88 y versiones posteriores

Propiedades

  • tabId

    number opcional

    Es el ID de la pestaña para la que se consultará el estado. Si no se especifica ninguna pestaña, se devuelve el estado no específico de la pestaña.

Métodos

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

Inhabilita la acción del navegador para una pestaña.

Parámetros

  • tabId

    number opcional

    Es el ID de la pestaña para la que se modificará la acción del navegador.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

Habilita la acción del navegador para una pestaña. La configuración predeterminada es habilitada.

Parámetros

  • tabId

    number opcional

    Es el ID de la pestaña para la que se modificará la acción del navegador.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

Obtiene el color de fondo de la acción del navegador.

Parámetros

  • detalles

    TabDetails

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: ColorArray) => void

Muestra

  • Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

Obtiene el texto de la insignia de la acción del navegador. Si no se especifica ninguna pestaña, se devuelve el texto de la insignia que no es específico de la pestaña.

Parámetros

  • detalles

    TabDetails

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: string) => void

    • resultado

      string

Muestra

  • Promise<string>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

Obtiene el documento HTML que se establece como la ventana emergente para esta acción del navegador.

Parámetros

  • detalles

    TabDetails

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: string) => void

    • resultado

      string

Muestra

  • Promise<string>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Obtiene el título de la acción del navegador.

Parámetros

  • detalles

    TabDetails

  • callback

    función opcional

    El parámetro callback se ve de la siguiente manera: 

    (result: string) => void

    • resultado

      string

Muestra

  • Promise<string>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

Establece el color de fondo de la insignia.

Parámetros

  • detalles

    objeto

    • color

      string | ColorArray

      Es un array de cuatro números enteros en el rango de 0 a 255 que conforman el color RGBA de la insignia. También puede ser una cadena con un valor de color hexadecimal de CSS, por ejemplo, #FF0000 o #F00 (rojo). Renderiza los colores con opacidad total.

    • tabId

      number 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 posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

Establece el texto de la insignia para la acción del navegador. La insignia se muestra sobre el ícono.

Parámetros

  • detalles

    objeto

    • tabId

      number opcional

      Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.

    • texto

      string opcional

      Se puede pasar cualquier cantidad de caracteres, pero solo caben unos cuatro en el espacio. Si se pasa una cadena vacía (''), se borra el texto de la insignia. Si se especifica tabId y text es nulo, se borra el texto de la pestaña especificada y se establece de forma predeterminada en el texto de la insignia global.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Establece el ícono para la acción del navegador. El ícono se puede especificar como la ruta de acceso a un archivo de imagen, como los datos de píxeles de un elemento de lienzo o como un diccionario de uno de esos elementos. 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 establecerá. Si el ícono se especifica como un diccionario, la imagen utilizada 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 selecciona una imagen con el tamaño scale * 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" equivale a "details.imageData = {'16': foo}".

    • ruta de acceso

      string | object opcional

      Es una ruta de acceso de imagen relativa o un diccionario {size -> relative image path} que apunta a un ícono que se establecerá. Si el ícono se especifica como un diccionario, la imagen utilizada 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 selecciona una imagen con el tamaño scale * 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" equivale a "details.path = {'16': foo}"

    • tabId

      number 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

Muestra

  • Promise<void>

    Chrome 116 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Establece 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

      string

      Es la ruta de acceso relativa al archivo HTML que se mostrará en una ventana emergente. Si se establece en la cadena vacía (''), no se muestra ninguna ventana emergente.

    • tabId

      number 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 posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

      number opcional

      Limita el cambio a cuando se selecciona una pestaña en particular. Se restablece automáticamente cuando se cierra la pestaña.

    • título

      string

      Es la cadena que debe mostrar la acción del navegador cuando se pasa el mouse por encima.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo se admiten en 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.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (tab: tabs.Tab) => void