chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza le azioni del browser per inserire icone nella barra degli strumenti principale di Google Chrome, a destra della barra degli indirizzi. Oltre alla sua icona, un'azione del browser può avere una tooltip, un badge e un popup.

Disponibilità

≤ MV2

Nella figura seguente, il quadrato multicolore a destra della barra degli indirizzi è l'icona di un'azione del browser. Sotto l'icona è presente un popup.

Se vuoi creare un'icona che non sia sempre attiva, utilizza un'azione di pagina anziché un'azione del browser.

Manifest

Registra l'azione del browser nel manifesto dell'estensione in questo modo:

{
  "name": "My extension",
  ...
  "browser_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
  },
  ...
}

Puoi fornire un'icona di qualsiasi dimensione da utilizzare in Chrome, che selezionerà quella più vicina e la ridimensionerà in modo che riempia lo spazio di 16 dip. Tuttavia, se non viene fornita la dimensione esatta, questo ridimensionamento può causare la perdita di dettagli o un aspetto sfocato dell'icona.

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. In questo modo, se le dimensioni di visualizzazione dell'icona vengono modificate, non dovrai fare altro per fornire icone diverse.

La vecchia sintassi per la registrazione dell'icona predefinita è ancora supportata:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Parti della UI

Un'azione del browser può avere un'icona, un tooltip, un badge e un popup.

Icona

Le icone delle azioni del browser in Chrome hanno una larghezza e un'altezza di 16 dip (pixel indipendenti dal dispositivo). Le icone più grandi vengono ridimensionate per adattarsi, ma per risultati ottimali utilizza un'icona quadrata di 16 dip.

Puoi impostare l'icona in due modi: utilizzando un'immagine statica o l'elemento canvas HTML5. L'utilizzo di immagini statiche è più semplice per le applicazioni semplici, ma puoi creare UI più dinamiche, come animazioni fluide, utilizzando l'elemento canvas.

Le immagini statiche possono essere in qualsiasi formato visualizzabile da WebKit, inclusi BMP, GIF, ICO, JPEG o PNG. Per le estensioni non pacchettizzate, le immagini devono essere in formato PNG.

Per impostare l'icona, utilizza il campo default_icon di browser_action nel manifest o chiama il metodo browserAction.setIcon.

Per visualizzare correttamente l'icona quando la densità di pixel dello schermo (rapporto size_in_pixel / size_in_dip) è diversa da 1, l'icona può essere definita come un insieme di immagini con dimensioni diverse. L'immagine effettiva da visualizzare verrà selezionata dal set per adattarsi al meglio alle dimensioni in pixel di 16 dip. Il set di icone può contenere specifiche di icone di qualsiasi dimensione e Chrome selezionerà quella più appropriata.

Tooltip

Per impostare il tooltip, utilizza il campo default_title di browser_action nel manifest o chiama il metodo browserAction.setTitle. Puoi specificare stringhe specifiche per le impostazioni internazionali per il campo default_title; per maggiori dettagli, consulta Internazionalizzazione.

Badge

Le azioni del browser possono facoltativamente mostrare un badge, ovvero un testo sovrapposto all'icona. I badge semplificano l'aggiornamento dell'azione del browser per visualizzare una piccola quantità di informazioni sullo stato dell'estensione.

Poiché lo spazio del badge è limitato, deve contenere al massimo 4 caratteri.

Imposta il testo e il colore del badge utilizzando rispettivamente browserAction.setBadgeText e browserAction.setBadgeBackgroundColor.

Se un'azione del browser ha un popup, questo viene visualizzato quando l'utente fa clic sull'icona dell'estensione. Il popup può contenere qualsiasi contenuto HTML e viene ridimensionato automaticamente in base ai contenuti. Il popup non può essere inferiore a 25 x 25 e non può essere superiore a 800 x 600.

Per aggiungere un popup all'azione del browser, crea un file HTML con i contenuti del popup. Specifica il file HTML nel campo default_popup di browser_action nel manifest o chiama il metodo browserAction.setPopup.

Suggerimenti

Per un impatto visivo ottimale, segui queste linee guida:

  • Utilizza le azioni del browser per le funzionalità che hanno senso sulla maggior parte delle pagine.
  • Non utilizzare le azioni del browser per funzionalità che hanno senso solo per alcune pagine. Utilizza invece le azioni sulla pagina.
  • Utilizza icone grandi e colorate che sfruttano al meglio lo spazio di 16 x 16 dip. Le icone delle azioni del browser dovrebbero sembrare un po' più grandi e pesanti rispetto alle icone delle azioni della pagina.
  • Non cercare di imitare l'icona del menu monocromatico di Google Chrome. Questo non funziona bene con i temi e, in ogni caso, le estensioni dovrebbero risaltare un po'.
  • Sì: utilizza la trasparenza alfa per aggiungere bordi sfumati all'icona. Poiché molte persone utilizzano i temi, l'icona deve avere un bell'aspetto su una varietà di colori di sfondo.
  • Non animare costantemente l'icona. È davvero fastidioso.

Esempi

Puoi trovare semplici esempi di utilizzo delle azioni del browser nella directory examples/api/browserAction. Per altri esempi e per assistenza nella visualizzazione del codice sorgente, consulta Esempi.

Tipi

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

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

Disattiva l'azione del browser per una scheda.

Parametri

  • tabId

    number optional

    L'ID della scheda per cui modificare l'azione del browser.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 e versioni successive

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

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

Attiva l'azione del browser per una scheda. L'impostazione predefinita è abilitata.

Parametri

  • tabId

    number optional

    L'ID della scheda per cui modificare l'azione del browser.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 e versioni successive

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

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

Recupera il colore di sfondo dell'azione del browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: ColorArray) => void

Resi

  • Chrome 88 e versioni successive

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

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

Recupera il testo del badge dell'azione del browser. Se non viene specificata alcuna scheda, viene restituito il testo del badge non specifico della scheda.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 88 e versioni successive

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

getPopup()

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

Recupera il documento HTML impostato come popup per questa azione del browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 88 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.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Recupera il titolo dell'azione del browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise<string>

    Chrome 88 e versioni successive

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

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

Imposta il colore di sfondo del badge.

Parametri

  • dettagli

    oggetto

    • colore

      string | ColorArray

      Un array di quattro numeri interi compresi tra 0 e 255 che compongono il colore RGBA del badge. Può anche essere una stringa con un valore di colore esadecimale CSS, ad esempio #FF0000 o #F00 (rosso). Visualizza i colori con opacità massima.

    • tabId

      number optional

      Limita la modifica a quando viene selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 e versioni successive

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

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

Imposta il testo del badge per l'azione del browser. Il badge viene visualizzato sopra l'icona.

Parametri

  • dettagli

    oggetto

    • tabId

      number optional

      Limita la modifica a quando viene selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

    • testo

      stringa facoltativa

      È possibile passare un numero qualsiasi di caratteri, ma solo circa quattro possono essere inseriti nello spazio. Se viene passata una stringa vuota (''), il testo del badge viene cancellato. Se viene specificato tabId e text è null, il testo della scheda specificata viene cancellato e viene utilizzato il testo del badge globale per impostazione predefinita.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 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.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Imposta l'icona per l'azione del browser. 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 elementi. È necessario specificare la proprietà path o imageData.

Parametri

  • dettagli

    oggetto

    • imageData

      ImageData | oggetto facoltativo

      Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta un'icona da impostare. Se l'icona è specificata come dizionario, l'immagine utilizzata 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, viene selezionata un'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 a un'icona da impostare. Se l'icona è specificata come dizionario, l'immagine utilizzata 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, viene selezionata un'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

      number optional

      Limita la modifica a quando viene selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 116 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.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

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

      number optional

      Limita la modifica a quando viene selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 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.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Imposta il titolo dell'azione del browser. Questo titolo viene visualizzato nel tooltip.

Parametri

  • dettagli

    oggetto

    • tabId

      number optional

      Limita la modifica a quando viene selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

    • titolo

      stringa

      La stringa che l'azione del browser deve visualizzare quando il mouse viene posizionato sopra.

  • callback

    funzione elemento facoltativo

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 88 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.browserAction.onClicked.addListener(
  callback: function,
)

Attivato quando si fa clic sull'icona di un'azione del browser. Non viene attivato se l'azione del browser ha un popup.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab) => void