chrome.browserAction

Descrizione

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

Disponibilità

≤ MV2

Nella figura che segue, il quadrato multicolore a destra della barra degli indirizzi è l'icona di un'azione nel browser. Sotto l'icona si trova un popup.

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

Manifest

Registra l'azione del browser nel manifest delle estensioni nel seguente 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 e Chrome ne selezionerà quella più vicina e la ridimensiona in base alle dimensioni appropriate per riempire lo spazio di 16 dip. Tuttavia, se non viene fornita la dimensione esatta, questo ridimensionamento può causare la perdita di dettagli o l'aspetto sfocato dell'icona.

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. In questo modo, inoltre, se le dimensioni di visualizzazione delle icone vengono modificate, non dovrai più lavorare 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 dell'interfaccia utente

Un'azione del browser può avere un'icona, una descrizione comando, un badge e un popup.

Icona

Le icone delle azioni del browser in Chrome sono larghe e alte 16 cali (pixel indipendenti dal dispositivo). Le icone più grandi vengono ridimensionate, ma per ottenere risultati ottimali, utilizza un'icona quadrata con 16 pixel.

Puoi impostare l'icona in due modi: con un'immagine statica o con l'elemento canvas HTML5. L'utilizzo di immagini statiche è più semplice nelle applicazioni semplici, ma è possibile creare UI più dinamiche, ad esempio 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 file manifest oppure chiama il metodo browserAction.setIcon.

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

Descrizione comando

Per impostare la descrizione comando, utilizza il campo default_title di browser_action nel file manifest oppure chiama il metodo browserAction.setTitle. Puoi specificare stringhe specifiche per le impostazioni internazionali per il campo default_title. Consulta Internazionalizzazione per i dettagli.

Badge

Le azioni del browser possono anche mostrare un badge, ovvero un frammento di testo sovrapposto all'icona. Con i badge è facile aggiornare l'azione del browser in modo da mostrare una piccola quantità di informazioni sullo stato dell'estensione.

Poiché lo spazio è limitato, il badge 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 contiene un popup, questo viene visualizzato quando l'utente fa clic sull'icona dell'estensione. Il popup può contenere tutti i contenuti HTML di tua scelta e viene ridimensionato automaticamente per adattarlo 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 file manifest oppure chiama il metodo browserAction.setPopup.

Suggerimenti

Per un impatto visivo ottimale, segui queste linee guida:

  • Utilizza le azioni del browser per le funzionalità pertinenti nella maggior parte delle pagine.
  • Non utilizzare le azioni del browser per funzionalità pertinenti solo per poche pagine. Utilizza le azioni sulle pagine.
  • Usa icone grandi e colorate che sfruttino al meglio lo spazio di 16 x 16 pixel. Le icone di azione del browser dovrebbero sembrare un po' più grandi e più pesanti delle icone di azione nelle pagine.
  • Non tentare di imitare l'icona del menu monocromatico di Google Chrome. Non funziona bene con i temi e, comunque, le estensioni dovrebbero risaltare un po'.
  • Sì. Usa la trasparenza alfa per aggiungere bordi sfumati all'icona. Poiché molte persone utilizzano i temi, l'icona deve essere visualizzata correttamente su uno sfondo di diversi colori.
  • Non animare costantemente l'icona. È solo un fastidio.

Esempi

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

Tipi

ColorArray

Tipo

[numero,numero,numero,numero]

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

disable()

Promessa 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Disattiva l'azione del browser per una scheda.

Parametri

  • tabId

    numero facoltativo

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

enable()

Promessa 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Attiva l'azione del browser per una scheda. Il valore predefinito è Attivato.

Parametri

  • tabId

    numero facoltativo

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

getBadgeBackgroundColor()

Promessa 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Recupera il colore di sfondo dell'azione del browser.

Parametri

Ritorni

  • Promise<ColorArray>

    Chrome 88 e versioni successive

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

getBadgeText()

Promessa 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

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

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string)=>void

    • risultato

      stringa

Ritorni

  • Promessa<string>

    Chrome 88 e versioni successive

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

getPopup()

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

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

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string)=>void

    • risultato

      stringa

Ritorni

  • Promessa<string>

    Chrome 88 e versioni successive

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

getTitle()

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

Restituisce il titolo dell'azione del browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string)=>void

    • risultato

      stringa

Ritorni

  • Promessa<string>

    Chrome 88 e versioni successive

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

setBadgeBackgroundColor()

Promessa 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Imposta il colore di sfondo del badge.

Parametri

  • dettagli

    oggetto

    • colore

      stringa|ColorArray

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

    • tabId

      numero facoltativo

      Limita la modifica al momento in cui viene selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

setBadgeText()

Promessa 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

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

Parametri

  • dettagli

    oggetto

    • tabId

      numero facoltativo

      Limita la modifica al momento in cui viene selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.

    • testo

      stringa facoltativo

      È possibile passare un numero qualsiasi di caratteri, ma lo spazio può contenere solo quattro caratteri. Se viene trasmessa una stringa vuota (''), il testo del badge viene cancellato. Se tabId viene specificato e text è null, il testo per la scheda specificata viene cancellato e per impostazione predefinita viene utilizzato il testo del badge globale.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

setIcon()

Promessa 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

Imposta l'icona per l'azione del browser. 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

    • imageData

      DatiImmagine|oggetto facoltativo

      Un oggetto ImageData o un dizionario {size -> ImageData} che rappresenta un'icona da impostare. Se l'icona viene 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à dello spazio dello schermo è uguale a scale, viene 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 a un'icona da impostare. Se l'icona viene 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à dello spazio dello schermo è uguale a scale, viene 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 facoltativo

      Limita la modifica al momento in cui viene selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 116 e versioni successive

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

setPopup()

Promessa 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

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

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 facoltativo

      Limita la modifica al momento in cui viene selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

setTitle()

Promessa 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Imposta il titolo dell'azione del browser. Questo titolo viene visualizzato nella descrizione comando.

Parametri

  • dettagli

    oggetto

    • tabId

      numero facoltativo

      Limita la modifica al momento in cui viene selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.

    • title

      stringa

      La stringa che dovrebbe visualizzare l'azione del browser al passaggio del mouse.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 88 e versioni successive

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

Eventi

onClicked

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

Attivato quando viene fatto clic su un'icona di azione del browser. Non si attiva se l'azione del browser ha un popup.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab)=>void