chrome.browserAction

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 descrizione comando, un badge e un popup.

Disponibilità

≤ MV2

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

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

Manifest

Registra l'azione del browser nel manifest dell'estensione 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 qualsiasi icona di dimensione da utilizzare in Chrome: Chrome selezionerà l'icona più vicina e ridimensionerà alle dimensioni appropriate per riempire lo spazio dei 16 dip. Tuttavia, se non vengono fornite le dimensioni esatte, il 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 più comuni, ti consigliamo di fornire più dimensioni per le icone. Questo assicura anche che, se le dimensioni di visualizzazione dell'icona cambia continuamente, non devi fare altro per creare 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 di 16 cali (pixel indipendenti dal dispositivo). Più grande le icone vengono ridimensionate per adattarsi, ma per ottenere i risultati migliori utilizza un'icona quadrata con 16 dita.

Puoi impostare l'icona in due modi: utilizzando un'immagine statica o l'elemento canvas HTML5. Utilizzo le immagini statiche sono più semplici per le applicazioni semplici, ma puoi creare UI più dinamiche, come un'animazione più fluida, utilizzando l'elemento canvas.

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

Per impostare l'icona, utilizza il campo default_icon di default_icon nel file manifest, oppure richiama 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 un insieme di immagini con dimensioni diverse. L'immagine effettiva da il display verrà selezionato tra quelli selezionati per adattarsi al meglio alle dimensioni in pixel di 16 dip. Il set di icone può contenere le specifiche per le icone di qualsiasi dimensione e Chrome selezionerà quella più appropriata.

Descrizione comando

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

Badge

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

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

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

Se per un'azione del browser è presente un popup, questo viene visualizzato quando l'utente fa clic sull'icona dell'estensione. La può includere tutti i contenuti HTML che preferisci e viene ridimensionato automaticamente per adattarsi a tali contenuti. Il popup non può essere più piccolo di 25 x 25 e non può essere più grande di 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 oppure richiama 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 le funzionalità significative solo per poche pagine. Usa pagina azioni.
  • Utilizza icone grandi e colorate che consentano di sfruttare al meglio lo spazio di 16 x 16 pixel. Icone di azione del browser dovrebbero sembrare un po' più grandi e più pesanti delle icone delle azioni sulle pagine.
  • Non tentare di imitare l'icona del menu monocromatico di Google Chrome. Non funziona bene con temi e, comunque, le estensioni dovrebbero risaltare un po'.
  • Sì. Utilizza la trasparenza alfa per aggiungere bordi morbidi all'icona. Poiché molte persone utilizzano i temi, dovrebbe avere un aspetto piacevole su vari colori di sfondo.
  • Non animare costantemente l'icona. È solo fastidioso.

Esempi

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

Tipi

ColorArray

Tipo

[numero, numero, numero, numero]

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

disable()

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

Disattiva l'azione del browser per una scheda.

Parametri

  • tabId

    numero facoltativo

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 88 e versioni successive .

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

enable()

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

Consente di attivare l'azione del browser per una scheda. Per impostazione predefinita, è abilitato.

Parametri

  • tabId

    numero facoltativo

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 88 e versioni successive .

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

getBadgeBackgroundColor()

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

Ottiene il colore di sfondo dell'azione del browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: ColorArray) => void

Resi

  • Promise&lt;ColorArray&gt;

    Chrome 88 e versioni successive .

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

getBadgeText()

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

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

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise&lt;string&gt;

    Chrome 88 e versioni successive .

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

getPopup()

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

Restituisce 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

Resi

  • Promise&lt;string&gt;

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

Restituisce il titolo dell'azione nel browser.

Parametri

  • dettagli

    TabDetails

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (result: string) => void

    • risultato

      stringa

Resi

  • Promise&lt;string&gt;

    Chrome 88 e versioni successive .

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

setBadgeBackgroundColor()

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

Imposta il colore di sfondo per il badge.

Parametri

  • dettagli

    oggetto

    • colore

      string | ColorArray

      Un array di quattro numeri interi nell'intervallo 0-255 che compongono il colore RGBA del badge. Può anche essere 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 alla selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 88 e versioni successive .

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

setBadgeText()

Promesso .
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 alla selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

    • testo

      stringa facoltativo

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

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

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

Consente di impostare l'icona dell'azione del browser. 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 file. È 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 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à di spazio sullo 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" equivale a "details.imageData = {'16': foo}"

    • percorso

      string | 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à di spazio sullo 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. Tieni presente che "details.path = foo" è equivalente a "details.path = {'16': foo}"

    • tabId

      numero facoltativo

      Limita la modifica alla selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

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

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

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 facoltativo

      Limita la modifica alla selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 88 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.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 alla selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.

    • titolo

      stringa

      La stringa visualizzata dall'azione del browser al passaggio del mouse.

  • callback

    funzione facoltativa

    Chrome 67 e versioni successive .

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 88 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.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 include un popup.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (tab: tabs.Tab) => void