browser.action

Descripción

Usa la API de chrome.action para controlar el ícono de la extensión en la barra de herramientas de Google Chrome.

Los íconos de acción se muestran en la barra de herramientas del navegador junto al cuadro multifunción. Después de la instalación, estas aparecen en el menú de extensiones (el ícono de pieza de rompecabezas). Los usuarios pueden fijar el ícono de tu extensión en la barra de herramientas.

Disponibilidad

Chrome 88 y versiones posteriores browser.* desde Chrome 148 MV3 y versiones posteriores

Manifiesto

Las siguientes claves se deben declarar en el manifiesto para usar esta API.

"action"

Para usar la API de browser.action, especifica un "manifest_version" de 3 y, luego, incluye la clave "action" en tu archivo de manifiesto.

Nota: Todas las extensiones tienen un ícono en la barra de herramientas de Chrome, incluso si no se agrega la clave "action" al 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 se incluye, la extensión se sigue mostrando 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 de la barra de herramientas de tu extensión y se establece con la clave "default_icon" en la clave "action" del 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 las imágenes. Chrome usa estos íconos para elegir qué escala de imagen usar. Si no se encuentra una coincidencia exacta, Chrome selecciona la 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 frecuentes, te recomendamos que proporciones varios tamaños para tus íconos. Esto también prepara tu extensión para el futuro ante posibles cambios en el tamaño de visualización de los íconos. Sin embargo, si solo proporcionas un tamaño, la clave "default_icon" también se puede establecer en una cadena con la ruta de acceso a un solo ícono en lugar de un diccionario.

También puedes llamar a action.setIcon() para configurar el ícono de tu extensión de forma programática especificando una ruta de imagen diferente o proporcionando un ícono generado de forma dinámica con el elemento de lienzo HTML o, si se configura desde un service worker de extensión, 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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

Nota: La API de action.setIcon() está diseñada para establecer una imagen estática. No uses imágenes animadas para tus íconos.

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 puede mostrar el motor de renderización de Blink, incluidos PNG, JPEG, BMP, ICO y otros. No se admite el formato SVG. Las extensiones sin empaquetar deben usar imágenes PNG.

Información sobre la herramienta (título)

La información sobre la herramienta o el título aparecen 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 leen los lectores de pantalla cuando se enfoca el botón.

La información sobre la herramienta predeterminada se configura 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

Las acciones pueden mostrar opcionalmente una "insignia", que es un poco de texto superpuesto sobre el ícono. Esto te permite actualizar la acción para mostrar 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. Como el espacio es limitado, recomendamos que el texto de la insignia tenga cuatro caracteres o menos.

Para crear una insignia, establécela de manera programática llamando a action.setBadgeBackgroundColor() y action.setBadgeText(). No hay un parámetro de configuración de insignia predeterminado en el manifiesto. Los valores de color de la insignia pueden ser un array de cuatro números enteros entre 0 y 255 que conforman el color RGBA de la insignia o una cadena con un valor de color CSS.

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Ventana emergente

La ventana emergente de una acción se muestra 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 contener cualquier contenido HTML que desees y se ajustará automáticamente para adaptarse a su contenido. El tamaño de la ventana emergente debe ser de entre 25 × 25 y 800 × 600 píxeles.

La ventana emergente se establece inicialmente con la propiedad "default_popup" 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 de acceso relativa diferente con el método action.setPopup().

Nota: El evento action.onClicked no se enviará si la acción de la extensión especificó una ventana emergente para mostrar cuando se hace clic en la pestaña actual.

Casos de uso

Estado por pestaña

Las acciones de extensión 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 establecer el texto de la insignia de una pestaña específica, haz lo siguiente:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Si se omite la propiedad tabId, el parámetro de configuración se trata como un parámetro de 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 (se puede hacer clic en ellas) en todas las pestañas. Puedes cambiar este valor predeterminado configurando la propiedad default_state en la clave action del manifiesto. Si default_state se establece en "disabled", la acción se inhabilita de forma predeterminada y se debe habilitar de manera programática para que se pueda hacer clic en ella. Si default_state se establece en "enabled" (el valor predeterminado), la acción se habilita y se puede hacer clic en ella de forma predeterminada.

Puedes controlar el estado de manera programática con los métodos action.enable() y action.disable(). Esto solo afecta si la ventana emergente (si la hay) o el evento action.onClicked se envían 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 usan las acciones en las extensiones. Para probar esta API, instala el ejemplo de la API de Action desde el repositorio chrome-extension-samples.

Muestra 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 la ventana emergente.

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

Cómo insertar una secuencia de comandos de contenido cuando se hace 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 muestra 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 de contenido muestra una alerta para verificar que todo haya funcionado 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
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

Tipos

OpenPopupOptions

Chrome 99 y versiones posteriores browser.* desde Chrome 148

Propiedades

• windowId

  number opcional

  Es el ID de la ventana en la que se abrirá la ventana emergente de acción. Si no se especifica, se establece de forma predeterminada en la ventana activa en ese momento.

TabDetails

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.

UserSettings

Chrome 91 y versiones posteriores browser.* desde Chrome 148

Es la colección de parámetros de configuración especificados por el usuario relacionados con la acción de una extensión.

Propiedades

• isOnToolbar

  booleano

  Indica si el ícono de acción de la extensión está visible en la barra de herramientas de nivel superior de las ventanas del navegador (es decir, si el usuario "fijó" la extensión).

UserSettingsChange

Chrome 130 y versiones posteriores browser.* desde Chrome 148

Propiedades

• isOnToolbar

  booleano opcional

  Indica si el ícono de acción de la extensión está 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()

browser.action.disable(
  tabId?: number,
): Promise<void>

Inhabilita la acción para una pestaña.

Parámetros

• tabId

  number opcional

  Es el ID de la pestaña para la que deseas modificar la acción.

Muestra

• Promise<void>

enable()

browser.action.enable(
  tabId?: number,
): Promise<void>

Habilita la acción para una pestaña. De forma predeterminada, las acciones están habilitadas.

Parámetros

• tabId

  number opcional

  Es el ID de la pestaña para la que deseas modificar la acción.

Muestra

• Promise<void>

getBadgeBackgroundColor()

browser.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

Obtiene el color de fondo de la acción.

Parámetros

• detalles

  TabDetails

Muestra

• Promise<extensionTypes.ColorArray>

getBadgeText()

browser.action.getBadgeText(
  details: TabDetails,
): Promise<string>

Obtiene el texto de la insignia de la acción. Si no se especifica ninguna pestaña, se devuelve el texto de la insignia que no es específico de la pestaña. Si se habilita displayActionCountAsBadgeText, se devolverá un texto de marcador de posición, a menos que esté presente el permiso declarativeNetRequestFeedback o se haya proporcionado un texto de insignia específico de la pestaña.

Parámetros

• detalles

  TabDetails

Muestra

• Promise<string>

getBadgeTextColor()

Chrome 110 y versiones posteriores browser.* desde Chrome 148

browser.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

Obtiene el color del texto de la acción.

Parámetros

• detalles

  TabDetails

Muestra

• Promise<extensionTypes.ColorArray>

getPopup()

browser.action.getPopup(
  details: TabDetails,
): Promise<string>

Obtiene el documento HTML establecido como ventana emergente para esta acción.

Parámetros

• detalles

  TabDetails

Muestra

• Promise<string>

getTitle()

browser.action.getTitle(
  details: TabDetails,
): Promise<string>

Obtiene el título de la acción.

Parámetros

• detalles

  TabDetails

Muestra

• Promise<string>

getUserSettings()

Chrome 91 y versiones posteriores browser.* desde Chrome 148

browser.action.getUserSettings(): Promise<UserSettings>

Devuelve la configuración especificada por el usuario relacionada con la acción de una extensión.

Muestra

• Promise<UserSettings>

isEnabled()

Chrome 110 y versiones posteriores browser.* desde Chrome 148

browser.action.isEnabled(
  tabId?: number,
): Promise<boolean>

Indica si la acción de la extensión está habilitada para una pestaña (o de forma global si no se proporciona tabId). Las acciones habilitadas con solo declarativeContent siempre devuelven un valor falso.

Parámetros

• tabId

  number opcional

  Es el ID de la pestaña para la que deseas verificar el estado habilitado.

Muestra

• Promise<boolean>

openPopup()

Chrome 127 y versiones posteriores browser.* desde Chrome 148

browser.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

Abre la ventana emergente de la extensión. Entre Chrome 118 y Chrome 126, esta opción solo está disponible para las extensiones instaladas por política.

Parámetros

• opciones

  OpenPopupOptions opcional

  Especifica las opciones para abrir la ventana emergente.

Muestra

• Promise<void>

setBadgeBackgroundColor()

browser.action.setBadgeBackgroundColor(
  details: object,
): 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 [0,255] que conforman el color RGBA de la insignia. Por ejemplo, el rojo opaco es [255, 0, 0, 255]. También puede ser una cadena con un valor de CSS, en el que el rojo opaco es #FF0000 o #F00.

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

Muestra

• Promise<void>

setBadgeText()

browser.action.setBadgeText(
  details: object,
): Promise<void>

Establece el texto de la insignia para la acción. 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.

Muestra

• Promise<void>

setBadgeTextColor()

Chrome 110 y versiones posteriores browser.* desde Chrome 148

browser.action.setBadgeTextColor(
  details: object,
): Promise<void>

Establece el color del texto de la insignia.

Parámetros

• detalles

  objeto

  • color

    string | ColorArray

    Es un array de cuatro números enteros en el rango [0,255] que conforman el color RGBA de la insignia. Por ejemplo, el rojo opaco es [255, 0, 0, 255]. También puede ser una cadena con un valor de CSS, en el que el rojo opaco es #FF0000 o #F00. Si no se establece este valor, se elegirá automáticamente un color que contraste con el color de fondo de la insignia para que el texto sea visible. No se establecerán los colores con valores alfa equivalentes a 0 y se mostrará un error.

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

Muestra

• Promise<void>

setIcon()

browser.action.setIcon(
  details: object,
): Promise<void>

Establece el ícono de 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 de 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 establecerá. Si el ícono se especifica como un diccionario, la imagen real que se usará 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á la 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

    Una ruta de acceso de imagen relativa o un diccionario {size -> relative image path} que apunte al ícono que se establecerá. Si el ícono se especifica como un diccionario, la imagen real que se usará 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á la 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.

Muestra

• Promise<void>

  Chrome 96 y versiones posteriores browser.* desde Chrome 148

setPopup()

browser.action.setPopup(
  details: object,
): Promise<void>

Establece el documento HTML que se abrirá como ventana emergente cuando el usuario haga clic en el ícono de la acción.

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.

Muestra

• Promise<void>

setTitle()

browser.action.setTitle(
  details: object,
): Promise<void>

Establece el título de la acción. Esto se muestra 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 cuando se pasa el mouse por encima.

Muestra

• Promise<void>

Eventos

onClicked

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

Parámetros

• callback

  función

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

  (tab: tabs.Tab) => void

  • tabulación

    tabs.Tab

onUserSettingsChanged

Chrome 130 y versiones posteriores browser.* desde Chrome 148

browser.action.onUserSettingsChanged.addListener(
  callback: function,
)

Se activa cuando cambian los parámetros de configuración especificados por el usuario relacionados con la acción de una extensión.

Parámetros

• callback

  función

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

  (change: UserSettingsChange) => void

  • cambiar

    UserSettingsChange