chrome.pageAction

refresh date: 2026-09-25 robots: noindex

Descripción

Usa la API de chrome.pageAction para colocar íconos en la barra de herramientas principal de Google Chrome, a la derecha de la barra de direcciones. Las acciones de página representan acciones que se pueden realizar en la página actual, pero que no se aplican a todas las páginas. Las acciones de página aparecen inhabilitadas cuando están inactivas.

Disponibilidad

≤ MV2

Estos son algunos ejemplos:

  • Suscríbete al feed RSS de esta página
  • Crear una presentación de diapositivas con las fotos de esta página

El ícono de RSS de la siguiente captura de pantalla representa una acción de página que te permite suscribirte al feed RSS de la página actual.

Las acciones de página ocultas aparecen inhabilitadas. Por ejemplo, el feed RSS que aparece a continuación está inhabilitado, ya que no puedes suscribirte al feed de la página actual:

Te recomendamos que uses una acción del navegador para que los usuarios siempre puedan interactuar con tu extensión.

Manifiesto

Registra la acción de página en el manifiesto de la extensión de la siguiente manera:

{
  "name": "My extension",
  ...
  "page_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
  },
  ...
}

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. Chrome seleccionará el más cercano y lo escalará para llenar el espacio de 16 dips. Esto también garantiza que, si alguna vez se cambia el tamaño de visualización del ícono, no tendrás que hacer más trabajo para proporcionar íconos diferentes. Sin embargo, si la diferencia de tamaño es demasiado extrema, este escalamiento puede hacer que el ícono pierda detalles o se vea borroso.

Aún se admite la sintaxis anterior para registrar el ícono predeterminado:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Partes de la IU

Al igual que las acciones del navegador, las acciones de página pueden tener un ícono, un cuadro de información y una ventana emergente, pero no pueden tener insignias. Además, las acciones de la página pueden aparecer inhabilitadas. Puedes encontrar información sobre íconos, información sobre herramientas y ventanas emergentes leyendo sobre la IU de acciones del navegador.

Puedes hacer que aparezca una acción de página y que se inhabilite con los métodos pageAction.show y pageAction.hide, respectivamente. De forma predeterminada, una acción de página aparece inhabilitada. Cuando lo muestras, especificas la pestaña en la que debe aparecer el ícono. El ícono permanece visible hasta que se cierra la pestaña o comienza a mostrar una URL diferente (por ejemplo, porque el usuario hace clic en un vínculo).

Sugerencias

Para lograr el mejor impacto visual, sigue estos lineamientos:

  • Sí usa acciones de página para funciones que solo tengan sentido en algunas páginas.
  • No uses acciones de página para funciones que tengan sentido en la mayoría de las páginas. En su lugar, usa acciones del navegador.
  • No animes el ícono de forma constante. Eso es molesto.

Tipos

ImageDataType

Son los datos de píxeles de una imagen. Debe ser un objeto ImageData (por ejemplo, de un elemento canvas).

Tipo

ImageData

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

getPopup()

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

Obtiene el documento HTML establecido como la ventana emergente para esta acción de página.

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 101 y versiones posteriores

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

getTitle()

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

Obtiene el título de la acción de la página.

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 101 y versiones posteriores

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

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

Oculta la acción de la página. Las acciones de página ocultas siguen apareciendo en la barra de herramientas de Chrome, pero están inhabilitadas.

Parámetros

  • tabId

    número

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

  • callback

    función opcional

    Chrome 67 y versiones posteriores

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

    () => void

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setIcon()

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

Establece el ícono para la acción de la página. 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

    • iconIndex

      number opcional

      Obsoleto. Este argumento se ignora.

    • 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

      número

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

  • callback

    función opcional

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

    () => void

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setPopup()

Promise 
chrome.pageAction.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 la acción de página.

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

      número

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

  • callback

    función opcional

    Chrome 67 y versiones posteriores

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

    () => void

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setTitle()

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

Establece el título de la acción de página. Se muestra en un cuadro de información sobre la acción de la página.

Parámetros

  • detalles

    objeto

    • tabId

      número

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

    • título

      string

      Es la cadena de la información sobre la herramienta.

  • callback

    función opcional

    Chrome 67 y versiones posteriores

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

    () => void

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores

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

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

Muestra la acción de la página. La acción de página se muestra cada vez que se selecciona la pestaña.

Parámetros

  • tabId

    número

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

  • callback

    función opcional

    Chrome 67 y versiones posteriores

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

    () => void

Muestra

  • Promise<void>

    Chrome 101 y versiones posteriores

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

Eventos

onClicked

chrome.pageAction.onClicked.addListener(
  callback: function,
)

Se activa cuando se hace clic en un ícono de acción de página. Este evento no se activará si la acción de la página tiene una ventana emergente.

Parámetros

  • callback

    función

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

    (tab: tabs.Tab) => void