Descrizione
Utilizza l'API chrome.action
per controllare l'icona dell'estensione nella barra degli strumenti di Google Chrome.
Disponibilità
Manifest
Per utilizzare l'API chrome.action
, specifica un valore "manifest_version"
di 3
e includi
la chiave "action"
nel file manifest.
{
"name": "Action Extension",
...
"action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Click Me", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
La chiave "action"
(insieme alle relative chiavi secondarie) è facoltativa. Se non è inclusa, l'estensione viene comunque visualizzata nella barra degli strumenti per fornire l'accesso al relativo menu. Per questo motivo, ti consigliamo di includere sempre almeno le chiavi "action"
e "default_icon"
.
Concetti e utilizzo
Parti dell'interfaccia utente
Icona
L'icona è l'immagine principale nella barra degli strumenti dell'estensione ed è impostata dal tasto "default_icon"
in
la chiave "action"
del file manifest. Le icone devono avere una larghezza e un'altezza di 16 pixel indipendenti dal dispositivo (DIP).
La chiave "default_icon"
è un dizionario di dimensioni e percorsi delle immagini. Chrome utilizza queste icone
per scegliere la scala dell'immagine da utilizzare. Se non trova una corrispondenza esatta, Chrome seleziona quella più vicina
disponibili e le ridimensiona per adattarle all'immagine, con possibili ripercussioni sulla qualità dell'immagine.
Poiché i dispositivi con fattori di scala meno comuni, come 1,5x o 1,2x, stanno diventando più comuni, ti invitiamo a fornire più dimensioni per le icone. In questo modo, la tua estensione sarà al sicuro da potenziali modifiche delle dimensioni di visualizzazione delle icone. Tuttavia,
se fornisci un'unica dimensione, la chiave "default_icon"
può anche essere impostata su un
stringa con il percorso di una singola icona anziché di un dizionario.
Puoi anche chiamare action.setIcon()
per impostare l'icona dell'estensione in modo programmatico
specificando un percorso immagine diverso o fornendo un'icona generata dinamicamente utilizzando l'elemento canvas HTML oppure, se l'impostazione viene eseguita da un worker di servizio dell'estensione, l'API canvas offscreen.
const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00'; // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });
Per le estensioni pacchettizzate (installate da un file .crx), le immagini possono essere nella maggior parte dei formati che il Blink può visualizzare il motore di rendering, inclusi PNG, JPEG, BMP, ICO e altri. SVG non è supportato. Le estensioni scompattate devono utilizzare immagini PNG.
Descrizione comando (titolo)
La descrizione comando, o titolo, viene visualizzata quando l'utente posiziona il puntatore del mouse sull'icona dell'estensione nella barra degli strumenti. Viene incluso anche nel testo accessibile pronunciato dagli screen reader quando il pulsante acquisisce il focus.
La descrizione comando predefinita viene impostata utilizzando il campo "default_title"
della chiave "action"
in manifest.json
.
Puoi anche impostarlo in modo programmatico chiamando action.setTitle()
.
Badge
Le azioni possono mostrare facoltativamente un "badge" testo sovrapposto all'icona. In questo modo puoi aggiornare l'azione in modo da visualizzare una piccola quantità di informazioni sullo stato dell'estensione, ad esempio un contatore. Il badge ha un componente di testo e un colore di sfondo. Poiché lo spazio è limitato, consigliamo di utilizzare massimo quattro caratteri per il testo del badge.
Per creare un badge, impostalo in modo programmatico chiamando action.setBadgeBackgroundColor()
e
action.setBadgeText()
. Nel file manifest non è presente un'impostazione predefinita per il badge. I valori di colore del badge possono essere un array di quattro numeri interi compresi tra 0 e 255 che compongono il colore RGBA del badge o una stringa con un valore colore CSS.
chrome.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
chrome.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Popup
Il popup di un'azione viene visualizzato quando l'utente fa clic sul pulsante di azione dell'estensione nella barra degli strumenti. Il popup può contenere qualsiasi contenuto HTML e verrà ridimensionato automaticamente in base ai contenuti. Le dimensioni del popup devono essere comprese tra 25 x 25 e 800 x 600 pixel.
Il popup viene impostato inizialmente dalla proprietà "default_popup"
nella chiave "action"
del
manifest.json
file. Se presente, questa proprietà deve puntare a un percorso relativo all'interno dell'estensione
. Può anche essere aggiornato dinamicamente in modo da puntare a un percorso relativo diverso utilizzando il metodo
action.setPopup()
.
Casi d'uso
Stato per scheda
Le azioni di estensione possono avere stati diversi per ogni scheda. Per impostare un valore per un singolo
usa la proprietà tabId
nei metodi di impostazione dell'API action
. Ad esempio, per impostare il testo del badge per una scheda specifica, procedi nel seguente modo:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Se la proprietà tabId
viene tralasciata, l'impostazione viene considerata come un'impostazione globale. Specifico per la scheda
hanno la priorità su quelle globali.
Stato attivato
Per impostazione predefinita, le azioni della barra degli strumenti sono abilitate (cliccabili) in ogni scheda. Puoi controllare questa opzione utilizzando
action.enable()
e action.disable()
metodi. Questa opzione influisce solo sul popup (se presente) o
action.onClicked
evento viene inviato alla tua estensione; non influisce sulla presenza dell'azione
nella barra degli strumenti.
Esempi
Gli esempi seguenti mostrano alcuni modi comuni in cui le azioni vengono utilizzate nelle estensioni. Per provare questa API, installa l'esempio dell'API Action dal repository chrome-extension-samples.
Mostrare un popup
Capita spesso che in un'estensione venga visualizzato un popup quando l'utente fa clic sull'azione dell'estensione. A
implementalo nella tua estensione, dichiara il popup in manifest.json
e specifica
che Chrome dovrebbe visualizzare nel popup.
// manifest.json
{
"name": "Action popup demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to view a popup",
"default_popup": "popup.html"
}
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
<style>
html {
min-height: 5em;
min-width: 10em;
background: salmon;
}
</style>
</head>
<body>
<p>Hello, world!</p>
</body>
</html>
Inserire uno script di contenuti al clic
Un pattern comune per le estensioni è esporre la funzionalità principale utilizzando il parametro un'azione. L'esempio seguente mostra questo pattern. Quando l'utente fa clic sull'azione, l'estensione inserisce uno script di contenuti nella pagina corrente. Lo script dei contenuti mostra quindi un avviso per verificare che tutto abbia funzionato come previsto.
// manifest.json
{
"name": "Action script injection demo",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_title": "Click to show an alert"
},
"permissions": ["activeTab", "scripting"],
"background": {
"service_worker": "background.js"
}
}
// background.js
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content.js']
});
});
// content.js
alert('Hello, world!');
Emula azioni con contenuti dichiarativi
Questo esempio mostra come la logica di background di un'estensione può (a) disattivare un'azione per impostazione predefinita e (b) usare declarativeContent per attivarla su siti specifici.
// service-worker.js
// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
chrome.action.disable();
// Clear all rules to ensure only our expected rules are set
chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new chrome.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new chrome.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
chrome.declarativeContent.onPageChanged.addRules(rules);
});
});
Tipi
OpenPopupOptions
Proprietà
-
windowId
number facoltativo
L'ID della finestra in cui aprire il popup dell'azione. Se non specificato, il valore predefinito è la finestra attualmente attiva.
TabDetails
Proprietà
-
tabId
numero facoltativo
L'ID della scheda per cui eseguire la query. Se non viene specificata alcuna scheda, viene restituito lo stato non specifico per la scheda.
UserSettings
La raccolta di impostazioni specificate dall'utente relative all'azione di un'estensione.
Proprietà
-
isOnToolbar
booleano
Indica se l'icona di azione dell'estensione è visibile nelle finestre del browser barra degli strumenti di primo livello (ovvero se l'estensione è stata "bloccata" dall'utente).
UserSettingsChange
Proprietà
-
isOnToolbar
booleano facoltativo
Indica se l'icona di azione dell'estensione è visibile nelle finestre del browser barra degli strumenti di primo livello (ovvero se l'estensione è stata "bloccata" dall'utente).
Metodi
disable()
chrome.action.disable(
tabId?: number,
callback?: function,
)
Disattiva l'azione per una scheda.
Parametri
-
tabId
numero facoltativo
L'ID della scheda per la quale vuoi modificare l'azione.
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Consente di attivare l'azione per una scheda. Le azioni sono attivate per impostazione predefinita.
Parametri
-
tabId
numero facoltativo
L'ID della scheda per la quale vuoi modificare l'azione.
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Restituisce il colore di sfondo dell'azione.
Parametri
-
dettagli
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:(result: ColorArray) => void
-
risultato
-
Resi
-
Promise<browserAction.ColorArray>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Recupera il testo del badge relativo all'azione. Se non viene specificata alcuna scheda, viene restituito il testo del badge non specifico per la scheda. Se l'opzione displayActionCountAsBadgeText è abilitata, verrà restituito un testo segnaposto a meno che non sia presente l'autorizzazione declarativeNetRequestFeedback o non sia stato fornito il testo del badge specifico per la scheda.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Resi
-
Promesso<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Ottiene il colore del testo dell'azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: ColorArray) => void
-
risultato
-
Resi
-
Promise<browserAction.ColorArray>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Recupera il documento HTML impostato come popup per questa azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Resi
-
Promesso<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Recupera il titolo dell'azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(result: string) => void
-
risultato
stringa
-
Resi
-
Promesso<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Restituisce le impostazioni specificate dall'utente relative all'azione di un'estensione.
Parametri
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:(userSettings: UserSettings) => void
-
userSettings
-
Resi
-
Promise<UserSettings>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Indica se l'azione dell'estensione è attiva per una scheda (o a livello globale se non viene fornito alcun tabId
). Le azioni abilitate utilizzando solo declarativeContent
restituiscono sempre false.
Parametri
-
tabId
numero facoltativo
L'ID della scheda per la quale vuoi controllare lo stato attivo.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(isEnabled: boolean) => void
-
isEnabled
booleano
True se l'azione dell'estensione è attiva.
-
Resi
-
Promise<boolean>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Apre il popup dell'estensione. Tra Chrome 118 e Chrome 126, questa opzione è disponibile solo per le estensioni installate in base ai criteri.
Parametri
-
opzioni
OpenPopupOptions facoltativo
Specifica le opzioni per l'apertura del popup.
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setBadgeBackgroundColor()
chrome.action.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. Ad esempio, il rosso opaco è
[255, 0, 0, 255]
. Può anche essere una stringa con un valore CSS, con il rosso opaco#FF0000
o#F00
. -
tabId
number facoltativo
Limita la modifica al momento della 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>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Imposta il testo del badge per l'azione. Il badge viene visualizzato sopra l'icona.
Parametri
-
dettagli
oggetto
-
tabId
number facoltativo
Limita la modifica al momento in cui è selezionata una determinata scheda. Viene reimpostato automaticamente quando la scheda viene chiusa.
-
testo
stringa facoltativo
È possibile passare un numero qualsiasi di caratteri, ma nello spazio possono essere inseriti solo circa quattro caratteri. Se viene passata una stringa vuota (
''
), il testo del badge viene cancellato. SetabId
viene specificato etext
è nullo, il testo della scheda specificata viene cancellato e viene visualizzato per impostazione predefinita il testo del badge globale.
-
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setBadgeTextColor()
chrome.action.setBadgeTextColor(
details: object,
callback?: function,
)
Imposta il colore del testo per il badge.
Parametri
-
dettagli
oggetto
-
colore
stringa | ColorArray
Un array di quattro numeri interi nell'intervallo [0, 255] che compongono il colore RGBA del badge. Ad esempio, il rosso opaco è
[255, 0, 0, 255]
. Può anche essere una stringa con un valore CSS, dove il rosso opaco è#FF0000
o#F00
. Se non imposti questo valore, verrà scelto automaticamente un colore in contrasto con il colore di sfondo del badge in modo che il testo sia visibile. I colori con valori alfa equivalenti a 0 non verranno impostati e restituiranno un errore. -
tabId
number facoltativo
Limita la modifica al momento della 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>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setIcon()
chrome.action.setIcon(
details: object,
callback?: function,
)
Imposta l'icona per l'azione. 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
-
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 da utilizzare effettiva viene scelta in base alla densità in pixel dello schermo. Se il numero di pixel dell'immagine che si adattano a un'unità di spazio sullo schermo è pari a
scale
, verrà selezionata l'immagine con dimensioniscale
* n, dove n è la dimensione dell'icona nell'interfaccia utente. È necessario specificare almeno un'immagine. Tieni presente che "details.imageData = foo" è equivalente 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 è specificata come dizionario, l'immagine effettiva 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 dimensioniscale
* 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
number facoltativo
Limita la modifica al momento della 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
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
Imposta il documento HTML da aprire come popup quando l'utente fa clic sull'icona dell'azione.
Parametri
-
dettagli
oggetto
-
popup
stringa
Il percorso relativo al file HTML da mostrare in un popup. Se il valore è impostato sulla stringa vuota (
''
), non viene visualizzato alcun popup. -
tabId
number facoltativo
Limita la modifica al momento della selezione di una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.
-
-
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma sono disponibili callback per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La si risolve con lo stesso tipo passato al callback.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Imposta il titolo dell'azione. Questo viene visualizzato nella descrizione comando.
Parametri
-
dettagli
oggetto
-
tabId
number facoltativo
Limita la modifica al momento in cui è selezionata una determinata scheda. Viene reimpostata automaticamente quando la scheda viene chiusa.
-
titolo
stringa
La stringa che l'azione deve mostrare quando si passa il mouse sopra.
-
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.
Eventi
onClicked
chrome.action.onClicked.addListener(
callback: function,
)
Attivato quando viene fatto clic su un'icona delle azioni. Questo evento non viene attivato se l'azione ha un popup.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(tab: tabs.Tab) => void
-
tab
-
onUserSettingsChanged
chrome.action.onUserSettingsChanged.addListener(
callback: function,
)
Viene attivato quando le impostazioni specificate dall'utente relative all'azione di un'estensione cambiano.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(change: UserSettingsChange) => void
-
modifica
-