chrome.pageAction

Descrizione

Utilizza l'API chrome.pageAction per inserire icone nella barra degli strumenti principale di Google Chrome, a destra della barra degli indirizzi. Le azioni sulla pagina rappresentano azioni che possono essere intraprese nella pagina corrente, ma che non sono applicabili a tutte le pagine. Le azioni per la pagina appaiono in grigio quando sono inattive.

Disponibilità

≤ MV2

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 della pagina corrente.

Le azioni della pagina nascoste vengono visualizzate in grigio. Ad esempio, il feed RSS riportato di seguito è visualizzato in grigio perché non puoi iscriverti al feed per la pagina corrente:

Ti consigliamo di utilizzare un'azione del browser, in modo che gli utenti possano sempre interagire con la tua estensione.

Manifest

Registra l'azione di 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 più comuni, ti consigliamo di fornire più dimensioni per le icone. Chrome selezionerà quella più vicina e la ridimensionerà per riempire lo spazio di 16 dip. In questo modo, se le dimensioni di visualizzazione delle icone vengono modificate, non dovrai fare altro per fornire icone diverse. Tuttavia, se la differenza di dimensioni è troppo estrema, questo ridimensionamento può causare la perdita di dettagli o la sfocatura 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 le azioni del browser, le azioni della pagina possono avere un'icona, un suggerimento e un popup, ma non possono avere badge. Inoltre, le azioni della pagina possono essere visualizzate in grigio. Puoi trovare informazioni su icone, descrizioni comando e popup leggendo la sezione relativa all'interfaccia utente dell'azione del browser.

Puoi visualizzare e disattivare un'azione di pagina utilizzando rispettivamente i metodi pageAction.show e pageAction.hide. Per impostazione predefinita, un'azione sulla pagina viene visualizzata in grigio. Quando lo mostri, specifichi la scheda in cui deve essere visualizzata l'icona. L'icona rimane visibile finché la scheda non viene chiusa o non inizia a visualizzare un URL diverso (ad esempio perché l'utente fa clic su un link).

Suggerimenti

Per un impatto visivo ottimale, segui queste linee guida:

  • Utilizza le azioni sulla pagina per le funzionalità utili solo per alcune pagine.
  • Non utilizzare le azioni sulla pagina per le funzionalità utili per la maggior parte delle pagine. Utilizza invece le azioni del browser.
  • Non animare costantemente l'icona. È solo fastidioso.

Tipi

ImageDataType

Dati dei pixel per un'immagine. Deve essere un oggetto ImageData (ad esempio, da un elemento canvas).

Tipo

ImageData

TabDetails

Chrome 88+

Proprietà

  • tabId

    number (facoltativo)

    L'ID della scheda di cui eseguire una query sullo stato. Se non viene specificata alcuna scheda, viene restituito lo stato non specifico per le schede.

Metodi

getPopup()

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

Recupera il documento HTML impostato come popup per questa azione della pagina.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getTitle()

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

Recupera il titolo dell'azione sulla pagina.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

hide()

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

Nasconde l'azione della pagina. Le azioni della pagina nascoste vengono comunque visualizzate nella barra degli strumenti di Chrome, ma sono disattivate.

Parametri

  • tabId

    numero

    L'ID della scheda per la quale vuoi modificare l'azione di pagina.

  • callback

    funzione facoltativa

    Chrome 67+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

setIcon()

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

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. È necessario specificare la proprietà path o imageData.

Parametri

  • dettagli

    oggetto

    • iconIndex

      number (facoltativo)

      Deprecato. Questo argomento viene ignorato.

    • imageData

      ImageData | oggetto facoltativo

      Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta l'icona da impostare. Se l'icona è specificata come dizionario, l'immagine effettiva da utilizzare viene scelta in base alla densità dei pixel dello schermo. Se il numero di pixel dell'immagine che rientrano in un'unità di spazio dello schermo è uguale a scale, verrà selezionata l'immagine di dimensioni scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente che "details.imageData = foo" equivale 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 è specificata come dizionario, l'immagine effettiva da utilizzare viene scelta in base alla densità dei pixel dello schermo. Se il numero di pixel dell'immagine che rientrano in un'unità di spazio dello schermo è uguale a scale, verrà selezionata l'immagine di dimensioni scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente che "details.path = foo" equivale a "details.path = {'16': foo}".

    • tabId

      numero

      L'ID della scheda per la quale vuoi modificare l'azione di pagina.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

setPopup()

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

Imposta il documento HTML da aprire come popup quando l'utente fa clic sull'icona dell'azione sulla pagina.

Parametri

  • dettagli

    oggetto

    • popup

      stringa

      Il percorso relativo al file HTML da mostrare in un popup. Se impostato sulla stringa vuota (''), non viene visualizzato alcun popup.

    • tabId

      numero

      L'ID della scheda per la quale vuoi modificare l'azione di pagina.

  • callback

    funzione facoltativa

    Chrome 67+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

setTitle()

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

Imposta il titolo dell'azione sulla pagina. Questo valore viene visualizzato in una descrizione comando sopra l'azione della pagina.

Parametri

  • dettagli

    oggetto

    • tabId

      numero

      L'ID della scheda per la quale vuoi modificare l'azione di pagina.

    • titolo

      stringa

      La stringa della descrizione comando.

  • callback

    funzione facoltativa

    Chrome 67+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

show()

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

Mostra l'azione della pagina. L'azione di pagina viene mostrata ogni volta che viene selezionata la scheda.

Parametri

  • tabId

    numero

    L'ID della scheda per la quale vuoi modificare l'azione di pagina.

  • callback

    funzione facoltativa

    Chrome 67+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le 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.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab) => void