chrome.browserAction

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 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.

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.

Sugerencias

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]

ImageDataType

Datos de píxeles para una imagen. Debe ser un objeto ImageData, por ejemplo, de un elemento canvas.

Tipo

ImageData

TabDetails

Chrome 88 y versiones posteriores

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()

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

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

enable()

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

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getBadgeBackgroundColor()

Promesa 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

Parámetros

Devuelve

  • Promise<ColorArray>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getBadgeText()

Promesa 
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

    TabDetails

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

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getPopup()

Promesa 
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

    TabDetails

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

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

getTitle()

Promesa 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

      cadena

Devuelve

  • Promesa<string>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setBadgeBackgroundColor()

Promesa 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Establece el color de fondo para la insignia.

Parámetros

  • detalles

    objeto

    • color [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 posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setBadgeText()

Promesa 
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 especifica tabId y text 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 posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setIcon()

Promesa 
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ñ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” 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ñ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” 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 posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setPopup()

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

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.

setTitle()

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

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 88 y versiones posteriores

    Las 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.

Parámetros

  • callback

    la función

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

    (tab: tabs.Tab)=>void