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 sulla pagina corrente, ma che non sono applicabili a tutte le pagine. Le azioni per la pagina non sono selezionabili quando non sono attive.

Disponibilità

≤ MV2

Ecco alcuni esempi:

  • Iscriviti al feed RSS di questa pagina
  • Crea una presentazione dalle foto di questa pagina

L'icona RSS nello screenshot seguente rappresenta un'azione della pagina che ti consente di iscriverti a RSS. feed per la pagina corrente.

Le azioni nelle pagine nascoste vengono visualizzate in grigio. Ad esempio, il seguente feed RSS non è selezionabile perché non puoi iscriviti al feed della pagina corrente:

Valuta la possibilità di utilizzare un'azione nel browser, in modo che gli utenti possano sempre interagire con il tuo .

Manifest

Registra l'azione relativa alla pagina nel file 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à la più vicina e la ridimensionerà per riempire lo spazio dei 16 dip. Così, se le dimensioni di visualizzazione dell'icona dovessero cambiare, non per fornire icone diverse. Tuttavia, se la differenza di dimensione è troppo estrema, questo ridimensionamento può causare la perdita di dettagli o l'aspetto sfocato.

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 nel browser, le azioni sulle pagine possono avere un'icona, una descrizione comando e un popup. non possono avere badge, in ogni caso. Inoltre, le azioni sulla pagina possono non essere selezionabili. Puoi trovare informazioni su icone, le descrizioni comando e i popup leggendo le informazioni sull'interfaccia utente delle azioni del browser.

Puoi fare in modo che un'azione sulla pagina venga visualizzata e non selezionabile utilizzando pageAction.show e pageAction.hide rispettivamente. Per impostazione predefinita, un'azione pagina non è selezionabile. Quando devi specificare la scheda in cui deve essere visualizzata l'icona. L'icona rimane visibile finché la scheda viene chiuso o 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 nelle pagine per funzionalità pertinenti solo per poche pagine.
  • Non utilizzare le azioni sulla pagina per le funzionalità significative per la maggior parte delle pagine. Utilizzare le azioni del browser .
  • Non animare costantemente l'icona. È solo fastidioso.

Tipi

ImageDataType

Dati di 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 cui eseguire la query. Se non viene specificata alcuna tabulazione, viene restituito lo stato non specifico della scheda.

Metodi

getPopup()

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

Restituisce il documento HTML impostato come popup per l'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 e versioni successive .

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

getTitle()

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

Resi

  • Promise<string>

    Chrome 101 e versioni successive .

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

hide()

Promesso .
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

Nasconde l'azione della pagina. Le azioni nelle pagine nascoste vengono ancora visualizzate nella barra degli strumenti di Chrome, ma non sono selezionabili.

Parametri

  • tabId

    numero

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 101 e versioni successive .

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

setIcon()

Promesso .
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
)

Consente di impostare l'icona dell'azione della pagina. L'icona può essere specificata come percorso di un file immagine, come dati di pixel da 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

      ImageData | 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 effettivamente 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 è uguale a scale, verrà selezionata l'immagine con dimensioni scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Nota che "details.imageData = foo" equivale a "details.imageData = {'16': foo}"

    • percorso

      string | 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 effettivamente 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 è uguale a scale, verrà selezionata l'immagine con dimensioni scale * n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente che "details.path = foo" è equivalente a "details.path = {'16': foo}"

    • tabId

      numero

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

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 101 e versioni successive .

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

setPopup()

Promesso .
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 mostrare in una finestra popup. Se il valore è impostato sulla stringa vuota (''), non viene visualizzato alcun popup.

    • tabId

      numero

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 101 e versioni successive .

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

setTitle()

Promesso .
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
)

Imposta il titolo dell'azione della pagina. 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 della pagina.

    • titolo

      stringa

      La stringa della descrizione comando.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 101 e versioni successive .

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

show()

Promesso .
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

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

Parametri

  • tabId

    numero

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 101 e versioni successive .

    Le promesse 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 viene fatto clic su un'icona di azione della pagina. Questo evento non verrà attivato se l'azione della pagina include un popup.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab) => void