chrome.pageAction

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 la página representan acciones que se pueden realizar en la página actual, pero que no se pueden aplicar a todas las páginas. Las acciones de la página aparecen inhabilitadas cuando están inactivas.

Disponibilidad

≤ MV2

Estos son algunos ejemplos:

  • Suscribirse al feed RSS de esta página
  • Crea una presentación de diapositivas a partir de las fotos de esta página

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

Las acciones de páginas ocultas aparecen inhabilitadas. Por ejemplo, el siguiente feed RSS está inhabilitado, ya que no puedes suscribirte al feed de la página actual:

Considera usar una acción del navegador en su lugar, para que los usuarios siempre puedan interactuar con tu extensión.

Manifest

Registra la acción de tu página en el manifiesto de 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 comunes, te recomendamos que proporciones varios tamaños para tus íconos. Chrome seleccionará la opción más cercana y la escalará para llenar el espacio de 16 entradas. 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. 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 antigua 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, una información sobre la herramienta y una ventana emergente; sin embargo, no pueden tener insignias. Además, las acciones de la página pueden aparecer inhabilitadas. Para obtener más información sobre los íconos, la información sobre la herramienta y las ventanas emergentes, consulta la IU de acciones del navegador.

Puedes hacer que una acción de página se muestre y se inhabilite con los métodos pageAction.show y pageAction.hide, respectivamente. De forma predeterminada, las acciones de la página se muestran inhabilitadas. Cuando lo muestres, debes especificar la pestaña en la que debe aparecer el ícono. El ícono seguirá visible hasta que se cierre la pestaña o comience a mostrar una URL diferente (por ejemplo, porque el usuario hace clic en un vínculo).

Sugerencias

Para obtener el mejor impacto visual, sigue estos lineamientos:

  • Usa acciones de página para funciones que tengan sentido solo en unas pocas páginas.
  • No uses acciones de página en funciones que tengan sentido para la mayoría de las páginas. En su lugar, usa acciones del navegador.
  • No animes tu ícono constantemente. Eso es muy molesto.

Tipos

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

getPopup()

Promesa 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Obtiene el documento HTML configurado como ventana emergente para esta 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

      cadena

Devuelve

  • Promesa<string>

    Chrome 101 y versiones posteriores

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

getTitle()

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

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

      cadena

Devuelve

  • Promesa<string>

    Chrome 101 y versiones posteriores

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

hide()

Promesa 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

Oculta la acción de la página. Las acciones de páginas ocultas seguirán apareciendo en la barra de herramientas de Chrome, pero se verán inhabilitadas.

Parámetros

  • tabId

    número

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

  • callback

    Función opcional

    Chrome 67 y versiones posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setIcon()

Promesa 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
)

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 del lienzo, o como un diccionario de cualquiera de ellos. Se debe especificar la propiedad path o imageData.

Parámetros

  • detalles

    objeto

    • iconIndex

      número opcional

      Obsoleto. Se ignora este argumento.

    • imageData

      ImageData|objeto opcional

      Un objeto ImageData o un diccionario {size -> ImageData} que representa el ícono que se configurará. Si el ícono se especifica como un diccionario, se elige la imagen real que se usará 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 -> relativo a la ruta de la imagen} que apunta al ícono que se debe configurar. Si el ícono se especifica como un diccionario, se elige la imagen real que se usará 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

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

  • callback

    Función opcional

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setPopup()

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

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

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

  • callback

    Función opcional

    Chrome 67 y versiones posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 101 y versiones posteriores

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

setTitle()

Promesa 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
)

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

Parámetros

  • detalles

    objeto

    • tabId

      número

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

    • title

      cadena

      La cadena de 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

Devuelve

  • Promise<void>

    Chrome 101 y versiones posteriores

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

show()

Promesa 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

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

Parámetros

  • tabId

    número

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

  • callback

    Función opcional

    Chrome 67 y versiones posteriores

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

    ()=>void

Devuelve

  • Promise<void>

    Chrome 101 y versiones posteriores

    Las promesas solo son compatibles con 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 la página. Este evento no se activará si la acción de la página tiene una ventana emergente.

Parámetros

  • callback

    la función

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

    (tab: tabs.Tab)=>void