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
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).
Sugerencia
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
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()
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
-
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
Obtiene el título de la acción de la página.
Parámetros
-
detalles
-
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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
hide()
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 posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 101 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setIcon()
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ñoscale
* 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ñoscale
* 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 posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setPopup()
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 posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 101 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
setTitle()
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 posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 101 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
show()
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 posterioresEl parámetro
callback
se ve de la siguiente manera:() => void
Devuelve
-
Promise<void>
Chrome 101 y versiones posterioresLas 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.