chrome.pageAction

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à

≤ 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 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

Chrome 88 e versioni successive

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()

Promessa 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Restituisce 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

Ritorni

  • Promessa<string>

    Chrome 101 e versioni successive

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

getTitle()

Promessa 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Restituisce il titolo dell'azione della pagina.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string)=>void

    • risultato

      stringa

Ritorni

  • Promessa<string>

    Chrome 101 e versioni successive

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

hide()

Promessa 
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 successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 101 e versioni successive

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

setIcon()

Promessa 
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 dimensioni scale * 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 dimensioni scale * 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 successive

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

setPopup()

Promessa 
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 successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 101 e versioni successive

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

setTitle()

Promessa 
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 successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 101 e versioni successive

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

show()

Promessa 
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 successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 101 e versioni successive

    Le 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.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab)=>void