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 del í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 aparece a la derecha de la barra de direcciones es el ícono de un acción del navegador. Debajo del ícono, se muestra una ventana emergente.

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

Manifiesto

Registra la acción de tu 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, 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, esta puede 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 comunes, estás se recomienda que proporciones varios tamaños para tus iconos. Esto también garantiza que si el tamaño de visualización del ícono se modifica, no necesitas 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 disminuciones de ancho (píxeles independientes del dispositivo) de ancho y alto. Más grande se cambia el tamaño de los íconos para que se ajusten, pero para obtener mejores resultados, usa un ícono cuadrado de 16 dip.

Puedes configurar el ícono de dos maneras: usando una imagen estática o el elemento de lienzo de HTML5. Usando las imágenes estáticas son más fáciles para las aplicaciones simples, pero puedes crear IU más dinámicas, como animación fluida, con el elemento lienzo.

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

Para establecer el ícono, utiliza el campo default_icon de default_icon en el manifiesto. También puedes llamar a el 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 del número 1, el icono se puede definir como un conjunto de imágenes con diferentes tamaños. La imagen real la pantalla se seleccionará del conjunto para que se adapte mejor al tamaño de píxeles de 16 caídas. El conjunto de iconos puede contener especificación para í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 default_title en el manifiesto. llama al método browserAction.setTitle. Puedes especificar cadenas específicas de la configuración regional para los campo default_title; consulta Internacionalización para obtener más información.

Insignia

De manera opcional, las acciones del navegador pueden mostrar una insignia: 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.

Dado que 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. El puede incluir el contenido HTML que quieras, 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 superior a 800 x 600.

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

Sugerencias

Para lograr el mejor impacto visual, sigue estos lineamientos:

  • Usa las acciones del navegador para las funciones que sean relevantes en la mayoría de las páginas.
  • No uses las acciones del navegador para funciones que solo tengan sentido para unas pocas páginas. Usar página acciones en su lugar.
  • Usa íconos grandes y coloridos que aprovechen al máximo el espacio de 16 × 16 dip. Íconos de acción del navegador deberían parecer un poco más grandes y pesados que los íconos de acción de página.
  • No intentes imitar el ícono de menú monocromático de Google Chrome. Eso no funciona bien con temas y, de cualquier manera, las extensiones deberían destacarse un poco.
  • Usa la transparencia alfa para agregar bordes suaves a tu ícono. Debido a que muchas personas usan temas, tu debería verse bien en una variedad de colores de fondo.
  • No animes tu ícono constantemente. Eso es molesto.

Ejemplos

Puedes encontrar ejemplos sencillos de cómo usar las acciones del navegador en examples/api/browserAction. . Para ver otros ejemplos y ayuda para ver el 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, desde un elemento canvas.

Tipo

ImageData

TabDetails

Chrome 88 y versiones posteriores

Propiedades

  • tabId

    número opcional

    El ID de la pestaña para la que se consulta el estado. Si no se especifica ninguna pestaña, se devuelve un estado que no es específico de una 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 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

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

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

  • detalles

    TabDetails

  • callback

    función opcional

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

    (result: ColorArray) => void

Muestra

  • Promise&lt;ColorArray&gt;

    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 no específico de una 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

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

  • 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

      string

Muestra

  • 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 de la insignia.

Parámetros

  • detalles

    objeto

    • color

      string | ColorArray

      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 CSS. Por ejemplo, #FF0000 o #F00 (rojo). Renderiza colores con máxima opacidad.

    • tabId

      número opcional

      Limita el cambio al momento en que 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

  • Promesa<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 se muestra en la parte superior del ícono.

Parámetros

  • detalles

    objeto

    • tabId

      número opcional

      Limita el cambio al momento en que 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 pueden pasar cuatro caracteres en el espacio. Si se pasa una cadena vacía (''), se borrará el texto de la insignia. Si se especifica tabId y text tiene un valor 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

Muestra

  • Promesa<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 de 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 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 debe establecer. 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 la imagen que entran en una unidad de espacio de pantalla es igual a scale, se selecciona una imagen con el tamaño scale * n, en el que 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 | objeto opcional

      una ruta de imagen relativa o un diccionario {size -> Relative image path} que apunta a un ícono que se debe establecer. 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 la imagen que entran en una unidad de espacio de pantalla es igual a scale, se selecciona una imagen con el tamaño scale * n, en el que 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

      número opcional

      Limita el cambio al momento en que 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

  • Promesa<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 para que se abra como una ventana emergente cuando el usuario hace clic en el ícono de acción del navegador.

Parámetros

  • detalles

    objeto

    • ventana emergente

      string

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

    • tabId

      número opcional

      Limita el cambio al momento en que 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

  • Promesa<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 el cuadro de información.

Parámetros

  • detalles

    objeto

    • tabId

      número opcional

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

    • título

      string

      Es la cadena que la acción del navegador debe mostrar cuando se desplaza el mouse sobre ella.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

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

    () => void

Muestra

  • Promesa<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 muestra una ventana emergente.

Parámetros

  • callback

    función

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

    (tab: tabs.Tab) => void