Descrizione
Utilizza l'API chrome.pageAction
per inserire le icone nella barra degli strumenti principale di Google Chrome, a destra della barra degli indirizzi. Le azioni sulla pagina rappresentano le azioni che è possibile eseguire sulla pagina corrente, ma che non sono applicabili a tutte le pagine. Le azioni sulla pagina non sono selezionabili quando non sono attive.
Disponibilità
Ecco alcuni esempi:
- Iscriviti al feed RSS di questa pagina
- Crea una presentazione con le foto di questa pagina
L'icona RSS nello screenshot seguente rappresenta un'azione della pagina che ti consente di iscriverti al feed RSS per la pagina corrente.
Le azioni della pagina nascoste vengono visualizzate in grigio. Ad esempio, il feed RSS riportato di seguito non è selezionabile perché non puoi iscriverti al feed della pagina corrente:
Considera invece l'utilizzo di un'azione del browser, in modo che gli utenti possano sempre interagire con la tua estensione.
Manifest
Registra l'azione della pagina nel manifest dell'estensione nel seguente modo:
{
"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
},
...
}
Poiché i dispositivi con fattori di scala meno comuni, come 1,5x o 1,2x, stanno diventando sempre più comuni, ti consigliamo di fornire più dimensioni per le tue icone. Chrome seleziona quella più vicina e la scala per riempire lo spazio di 16 cali. In questo modo, inoltre, se le dimensioni di visualizzazione delle icone cambiano, non dovrai più lavorare per fornire icone diverse. Tuttavia, se la differenza di dimensioni è eccessiva, il ridimensionamento può causare la perdita di dettagli o l'aspetto sfocato dell'icona.
La vecchia sintassi per la registrazione dell'icona predefinita è ancora supportata:
{
"name": "My extension",
...
"page_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
Parti dell'interfaccia utente
Come per le azioni del browser, le azioni sulle pagine possono avere un'icona, una descrizione comando e un popup, ma non possono avere badge. Inoltre, le azioni sulle pagine possono non essere selezionabili. Per informazioni su icone, descrizioni comando e popup, leggi le informazioni sull'interfaccia utente delle azioni del browser.
Per rendere un'azione della pagina visualizzata e non selezionabile, utilizza rispettivamente i metodi pageAction.show
e
pageAction.hide
. Per impostazione predefinita, un'azione relativa alla pagina non è selezionabile. Quando la visualizzi, specifichi la scheda in cui deve essere visualizzata l'icona. L'icona rimane visibile fino a quando la scheda
viene chiusa o inizia a visualizzare un URL diverso (perché l'utente fa clic su un link, ad esempio).
Suggerimenti
Per un impatto visivo ottimale, segui queste linee guida:
- Utilizza le azioni nelle pagine per le funzionalità pertinenti solo per poche pagine.
- Non utilizzare le azioni nelle pagine per le funzionalità pertinenti per la maggior parte delle pagine. Utilizza invece le azioni nel browser.
- Non animare costantemente l'icona. È solo un fastidio.
Tipi
ImageDataType
Dati pixel per un'immagine. Deve essere un oggetto ImageData (ad esempio, da un elemento canvas
).
Tipo
ImageData
TabDetails
Proprietà
-
tabId
numero facoltativo
L'ID della scheda per la quale vuoi eseguire la query. Se non viene specificata alcuna scheda, viene restituito lo stato non specifico della scheda.
Metodi
getPopup()
chrome.pageAction.getPopup(
details: TabDetails,
callback?: function,
)
Restituisce il documento HTML impostato come popup per questa azione della pagina.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getTitle()
chrome.pageAction.getTitle(
details: TabDetails,
callback?: function,
)
Restituisce il titolo dell'azione della pagina.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
hide()
chrome.pageAction.hide(
tabId: number,
callback?: function,
)
Nasconde l'azione della pagina. Le azioni nascoste nelle pagine vengono comunque visualizzate nella barra degli strumenti di Chrome, ma non sono selezionabili.
Parametri
-
tabId
numero
L'ID della scheda per cui vuoi modificare l'azione della pagina.
-
callback
funzione facoltativa
Chrome 67 e versioni successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setIcon()
chrome.pageAction.setIcon(
details: object,
callback?: function,
)
Imposta l'icona per l'azione della pagina. L'icona può essere specificata come percorso di un file immagine, come dati in pixel di un elemento canvas o come dizionario di uno di questi elementi. È necessario specificare la proprietà path o imageData.
Parametri
-
dettagli
oggetto
-
iconIndex
numero facoltativo
Obsoleta. Questo argomento viene ignorato.
-
imageData
DatiImmagine | oggetto facoltativo
Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta l'icona da impostare. Se l'icona viene specificata come dizionario, l'immagine effettiva da utilizzare viene scelta in base alla densità dei pixel dello schermo. Se il numero di pixel immagine che rientrano in un'unità dello spazio sullo schermo è uguale a
scale
, verrà selezionata un'immagine con dimensioniscale
* n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Nota che "details.imageData = foo" è equivalente a "details.imageData = {'16': foo}". -
percorso
stringa | oggetto facoltativo
Un percorso dell'immagine relativo o un dizionario {size -> relative image path} che punta all'icona da impostare. Se l'icona viene specificata come dizionario, l'immagine effettiva da utilizzare viene scelta in base alla densità dei pixel dello schermo. Se il numero di pixel immagine che rientrano in un'unità dello spazio sullo schermo è uguale a
scale
, verrà selezionata un'immagine con dimensioniscale
* n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Nota che "details.path = foo" è equivalente a "details.path = {'16': foo}" -
tabId
numero
L'ID della scheda per cui vuoi modificare l'azione della pagina.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setPopup()
chrome.pageAction.setPopup(
details: object,
callback?: function,
)
Imposta il documento HTML da aprire come popup quando l'utente fa clic sull'icona dell'azione della pagina.
Parametri
-
dettagli
oggetto
-
popup
stringa
Il percorso relativo del file HTML da visualizzare in un popup. Se impostato sulla stringa vuota (
''
), non viene mostrato alcun popup. -
tabId
numero
L'ID della scheda per cui vuoi modificare l'azione della pagina.
-
-
callback
funzione facoltativa
Chrome 67 e versioni successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setTitle()
chrome.pageAction.setTitle(
details: object,
callback?: function,
)
Imposta il titolo dell'azione della pagina. Questo viene visualizzato in una descrizione comando sopra l'azione della pagina.
Parametri
-
dettagli
oggetto
-
tabId
numero
L'ID della scheda per cui vuoi modificare l'azione della pagina.
-
title
stringa
La stringa della descrizione comando.
-
-
callback
funzione facoltativa
Chrome 67 e versioni successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
show()
chrome.pageAction.show(
tabId: number,
callback?: function,
)
Mostra l'azione della pagina. L'azione della pagina viene visualizzata ogni volta che viene selezionata la scheda.
Parametri
-
tabId
numero
L'ID della scheda per cui vuoi modificare l'azione della pagina.
-
callback
funzione facoltativa
Chrome 67 e versioni successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 101 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
Eventi
onClicked
chrome.pageAction.onClicked.addListener(
callback: function,
)
Attivato quando viene fatto clic su un'icona di azione sulla pagina. Questo evento non viene attivato se l'azione della pagina ha un popup.