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 di "manifest_version" pari a 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 ai relativi elementi secondari) è facoltativa. Quando non è inclusa, l'estensione è comunque visualizzata nella barra degli strumenti per consentire l'accesso al menu dell'estensione. 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 dalla chiave "default_icon" nella chiave "action" del file manifest. Le icone devono avere una dimensione di 16 pixel indipendenti dal dispositivo (DIP) in larghezza e altezza.
La chiave "default_icon" è un dizionario di dimensioni e percorsi di immagini. Chrome usa queste icone
per scegliere la scala delle immagini da usare. Se non viene trovata una corrispondenza esatta, Chrome seleziona quella disponibile più vicina e la ridimensiona in base all'immagine, il che potrebbe influire sulla qualità dell'immagine.
Poiché i dispositivi con fattori di scala meno comuni, come 1,5x o 1,2x, stanno diventando sempre più comuni, ti invitiamo a fornire più dimensioni per le icone. In questo modo, l'estensione è predisposta per evitare potenziali variazioni delle dimensioni di visualizzazione delle icone.
Puoi anche chiamare action.setIcon() per impostare l'icona dell'estensione in modo programmatico
specificando un percorso dell'immagine diverso o fornendo un'icona generata dinamicamente utilizzando l'elemento canvas HTML o, se l'impostazione viene eseguita da un service worker delle estensioni,
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 supportati dal motore di rendering Blink, inclusi PNG, JPEG, BMP, ICO e altri. SVG non supportato. Le estensioni non pacchettizzate devono utilizzare immagini PNG.
Descrizione comando (titolo)
La descrizione comando, o titolo, viene visualizzata quando l'utente tiene il puntatore del mouse sopra l'icona dell'estensione nella barra degli strumenti. È inoltre incluso nel testo accessibile pronunciato dagli screen reader quando il pulsante viene attivato.
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 facoltativamente mostrare un "badge", ovvero un po' di testo sovrapposto all'icona. Questo ti consente di aggiornare l'azione per 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 al 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 dei colori del badge
possono essere un array di quattro numeri interi compresi tra 0 e 255 che costituiscono 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 tutti i contenuti HTML di tuo gradimento e verrà ridimensionato automaticamente per adattarlo ai relativi 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" nel
file manifest.json. Se presente, questa proprietà deve indirizzare a un percorso relativo all'interno della directory dell'estensione. Può anche essere aggiornato in modo dinamico in modo che punti a un percorso relativo diverso utilizzando il
metodo action.setPopup().
casi d'uso
Stato per scheda
Le azioni delle estensioni possono avere stati diversi per ogni scheda. Per impostare un valore per una singola
scheda, utilizza la proprietà tabId nei metodi di impostazione dell'API action. Ad esempio, per impostare il testo del badge per una scheda specifica:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Se la proprietà tabId viene tralasciata, l'impostazione viene considerata un'impostazione globale. Le impostazioni specifiche delle schede hanno la priorità sulle impostazioni globali.
Stato abilitato
Per impostazione predefinita, le azioni della barra degli strumenti sono attive (selezionabili) in ogni scheda. Puoi controllare questa opzione utilizzando i
metodi action.enable() e action.disable(). Questa impostazione influisce solo sull'invio dell'evento popup (se presente) o action.onClicked all'estensione; non influisce sulla presenza dell'azione nella barra degli strumenti.
Esempi
I seguenti esempi mostrano alcuni modi comuni in cui le azioni vengono utilizzate nelle estensioni. Per provare questa API, installa l'esempio di API Action dal repository chrome-extension-samples.
Mostra un popup
È comune che un'estensione mostri un popup quando l'utente fa clic sull'azione corrispondente. Per implementarla nella tua estensione, dichiara il popup in manifest.json e specifica i contenuti che Chrome deve 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>
Inserisci uno script di contenuti al clic
Un pattern comune per le estensioni è esporre la caratteristica principale utilizzando l'azione dell'estensione. 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 declarativeContent
Questo esempio mostra in che modo la logica in background di un'estensione può (a) disattivare un'azione per impostazione predefinita e (b) utilizzare declarativeContent per attivare l'azione 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
numero 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 la quale vuoi eseguire la query. Se non viene specificata alcuna scheda, viene restituito lo stato non specifico della scheda.
UserSettings
La raccolta di impostazioni specificate dall'utente relative all'azione di un'estensione.
Proprietà
-
isOnToolbar
boolean
Indica se l'icona di azione dell'estensione è visibile sulla barra degli strumenti di primo livello della finestra del browser (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 cui vuoi modificare l'azione.
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Attiva l'azione per una scheda. Le azioni sono abilitate per impostazione predefinita.
Parametri
-
tabId
numero facoltativo
L'ID della scheda per cui vuoi modificare l'azione.
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Recupera il colore di sfondo dell'azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(result: ColorArray)=>void
-
risultato
-
Ritorni
-
Promise<browserAction.ColorArray>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Recupera il testo del badge dell'azione. Se non viene specificata alcuna scheda, viene restituito il testo del badge non specifico per la scheda. Se displayActionCountAsBadgeText è attivato, verrà restituito un testo del segnaposto a meno che non sia presente l'autorizzazione declarativeNetRequestFeedback o non sia stato fornito un testo del badge specifico per la scheda.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(result: string)=>void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Restituisce il colore del testo dell'azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(result: ColorArray)=>void
-
risultato
-
Ritorni
-
Promise<browserAction.ColorArray>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Restituisce il documento HTML impostato come popup per questa azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(result: string)=>void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Recupera il titolo dell'azione.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(result: string)=>void
-
risultato
stringa
-
Ritorni
-
Promessa<string>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
getUserSettings()
chrome.action.getUserSettings(
callback?: function,
)
Restituisce le impostazioni specificate dall'utente relative all'azione di un'estensione.
Parametri
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(userSettings: UserSettings)=>void
-
userSettings
-
Ritorni
-
Promise<UserSettings>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
isEnabled()
chrome.action.isEnabled(
tabId?: number,
callback?: function,
)
Indica se l'azione dell'estensione è attivata per una scheda (o a livello globale se non viene fornito alcun tabId). Le azioni attivate utilizzando solo declarativeContent restituiscono sempre false.
Parametri
-
tabId
numero facoltativo
L'ID della scheda per cui vuoi controllare lo stato Attivato.
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:(isEnabled: boolean)=>void
-
isEnabled
boolean
True se l'azione dell'estensione è attivata.
-
Ritorni
-
Promise<boolean>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Apre il popup dell'estensione.
Parametri
-
opzioni
OpenPopupOptions facoltativo
Specifica le opzioni per l'apertura del popup.
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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ò essere anche una stringa con un valore CSS, dove il rosso opaco è#FF0000o#F00. -
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
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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
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. SetabIdviene 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
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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ò essere anche una stringa con un valore CSS, dove il rosso opaco è#FF0000o#F00. Se non imposti questo valore, verrà scelto automaticamente un colore che contrasterà con il colore di sfondo del badge, in modo che il testo sia visibile. I colori con valori alpha equivalenti a 0 non verranno impostati e restituiranno un errore. -
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
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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 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 l'icona da impostare. Se l'icona viene 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à dello spazio sullo schermo è uguale a
scale, verrà 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 all'icona da impostare. Se l'icona viene 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à dello spazio sullo schermo è uguale a
scale, verrà 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
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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 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
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.
setTitle()
chrome.action.setTitle(
details: object,
callback?: function,
)
Imposta il titolo dell'azione. Questo verrà 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 al passaggio del mouse.
-
-
callback
funzione facoltativa
Il parametro
callbackha il seguente aspetto:()=>void
Ritorni
-
Promise<void>
Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.