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à
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
.
Popup
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
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()
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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
enable()
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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Recupera il colore di sfondo dell'azione del browser.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: ColorArray) => void
-
risultato
-
Ritorni
-
Promise<ColorArray>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getBadgeText()
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
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Recupera il documento HTML impostato come popup per questa azione del browser.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Restituisce il titolo dell'azione del browser.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Imposta il colore di sfondo del badge.
Parametri
-
dettagli
oggetto
-
color
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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setBadgeText()
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. SetabId
viene specificato etext
è 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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setIcon()
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 dimensioniscale
* 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 dimensioniscale
* 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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setPopup()
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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setTitle()
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 successiveIl parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 88 e versioni successiveLe 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.