chrome.pageAction

refresh date: 2026-09-25 robots: noindex

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 della pagina vengono visualizzate 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 tue icone. Chrome selezionerà quello più vicino e lo 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 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 della UI

Come le azioni del browser, le azioni della pagina possono avere un'icona, una descrizione comando e un popup, ma non possono avere badge. Inoltre, le azioni della pagina possono essere disattivate. Puoi trovare informazioni su icone, descrizioni comando e popup leggendo l'articolo sull'interfaccia utente delle azioni 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 a livello di 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. È davvero 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 optional

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

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 sulla 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 dei pixel di un elemento canvas o come dizionario di uno di questi. È necessario specificare la proprietà path o imageData.

Parametri

  • dettagli

    oggetto

    • iconIndex

      number optional

      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 relativo dell'immagine 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 della pagina.

Parametri

  • dettagli

    oggetto

    • popup

      stringa

      Il percorso relativo al file HTML da mostrare in un popup. Se viene 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. Viene visualizzata 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 della 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 della pagina. Questo evento non verrà attivato se l'azione della pagina ha un popup.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab) => void