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 le azioni che possono essere eseguite sulla pagina corrente, ma che non sono applicabili a tutte le pagine. Le azioni della pagina vengono visualizzate in grigio quando non sono attive.

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 per la pagina corrente.

Le azioni della pagina nascoste vengono visualizzate in grigio. Ad esempio, il feed RSS di seguito è in grigio, in quanto 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 sulla pagina nel manifest dell'estensione in questo 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 scalabilità meno comuni, come 1,5x o 1,2x, stanno diventando più comuni, ti consigliamo di fornire più dimensioni per le tue icone. Chrome selezionerà quella più vicina e la ridimensionerà per riempire lo spazio di 16 dip. In questo modo, se le dimensioni di visualizzazione dell'icona 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 un 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, un tooltip e un popup, ma non possono avere badge. Inoltre, le azioni della pagina possono essere disattivate. Puoi trovare informazioni su icone, tooltip e popup leggendo la sezione relativa alla UI delle azioni del browser.

Puoi fare in modo che un'azione di pagina venga visualizzata e sia disattivata utilizzando rispettivamente i metodi pageAction.show e pageAction.hide. Per impostazione predefinita, un'azione di pagina viene visualizzata in grigio. Quando la 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 mostrare un URL diverso (ad esempio perché l'utente fa clic su un link).

Suggerimenti

Per un impatto visivo ottimale, segui queste linee guida:

  • Sì: utilizza le azioni di pagina per le funzionalità che hanno senso solo per alcune pagine.
  • Non utilizzare le azioni di pagina per funzionalità che hanno senso per la maggior parte delle pagine. Utilizza invece le azioni del browser.
  • Non animare costantemente l'icona. È davvero fastidioso.

Tipi

ImageDataType

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

Tipo

ImageData

TabDetails

Chrome 88 e versioni successive

Proprietà

  • tabId

    number optional

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

Metodi

getPopup()

Promise 
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 elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 101 e versioni successive

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

getTitle()

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

Recupera il titolo dell'azione della pagina.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 101 e versioni successive

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

hide()

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

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

Parametri

  • tabId

    numero

    L'ID della scheda per cui vuoi modificare l'azione sulla pagina.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

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

setIcon()

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

Imposta l'icona per l'azione sulla pagina. L'icona può essere specificata come percorso di un file immagine o come dati dei pixel di un elemento canvas oppure come dizionario di uno dei due. È 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 immagine che rientrano in un'unità di spazio sullo schermo è pari a scale, verrà selezionata l'immagine con dimensioni scale * n, dove n è la dimensione dell'icona nella UI. È necessario specificare almeno un'immagine. Tieni presente che "details.imageData = foo" equivale a "details.imageData = {'16': foo}"

    • percorso

      string | object facoltativo

      Un percorso relativo dell'immagine o un dizionario {size -> relative image path} che rimanda 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 immagine che rientrano in un'unità di spazio sullo schermo è pari a scale, verrà selezionata l'immagine con dimensioni scale * n, dove n è la dimensione dell'icona nella UI. È necessario specificare almeno un'immagine. Tieni presente che "details.path = foo" equivale a "details.path = {'16': foo}"

    • tabId

      numero

      L'ID della scheda per cui vuoi modificare l'azione sulla pagina.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

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

setPopup()

Promise 
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 del file HTML da mostrare in un popup. Se viene impostato su una stringa vuota (''), non viene mostrato alcun popup.

    • tabId

      numero

      L'ID della scheda per cui vuoi modificare l'azione sulla pagina.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

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

setTitle()

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

Imposta il titolo dell'azione della pagina. Viene visualizzato in un tooltip sopra l'azione della pagina.

Parametri

  • dettagli

    oggetto

    • tabId

      numero

      L'ID della scheda per cui vuoi modificare l'azione sulla pagina.

    • titolo

      stringa

      La stringa del tooltip.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

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

show()

Promise 
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 cui vuoi modificare l'azione sulla pagina.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

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

Eventi

onClicked

chrome.pageAction.onClicked.addListener(
  callback: function,
)

Attivato quando si fa clic sull'icona di un'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