chrome.action

Descrizione

Disponibilità

Manifest

Per utilizzare l'API chrome.action, specifica un "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 ai relativi elementi secondari) è facoltativa. Quando non è incluso, l'estensione viene comunque visualizzata nella barra degli strumenti per fornire 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 sulla barra degli strumenti della tua estensione ed è impostata dalla chiave "default_icon" nella chiave "action" del 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 per i percorsi delle immagini. Chrome utilizza queste icone per scegliere la scala dell'immagine da utilizzare. Se non viene trovata una corrispondenza esatta, Chrome seleziona la corrispondenza più vicina disponibile e la ridimensiona per adattarla 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 più comuni, ti consigliamo di fornire più dimensioni per le tue icone. Inoltre, in questo modo l'estensione è protetta da potenziali modifiche alle dimensioni di visualizzazione delle icone. Tuttavia, se viene fornita una sola dimensione, la chiave "default_icon" può essere impostata anche su una stringa con il percorso di una singola icona anziché un dizionario.

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 oppure, se l'impostazione viene eseguita da un service worker dell'estensione, l'API canvas off-screen.

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 compresse (installate da un file .crx), le immagini possono essere nella maggior parte dei formati che il motore di rendering Blink può visualizzare, inclusi PNG, JPEG, BMP, ICO e altri. SVG non è supportato. Le estensioni non compresse 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. È incluso anche nel testo accessibile letto dagli screen reader quando il pulsante riceve 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 facoltativamente mostrare un "badge", ovvero un po' di testo sovrapposto all'icona. In questo modo puoi aggiornare l'azione per visualizzare una piccola quantità di informazioni sullo stato dell'estensione, ad esempio un contatore. Il badge è composto da un componente di testo e da un colore di sfondo. Poiché lo spazio è limitato, ti consigliamo di utilizzare un testo del badge di massimo quattro caratteri.

Per creare un badge, impostalo in modo programmatico chiamando action.setBadgeBackgroundColor() e action.setBadgeText(). Non esiste un'impostazione predefinita del badge nel manifest. I valori del 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 CSS color.

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 le sue dimensioni vengono regolate automaticamente in base ai contenuti. Le dimensioni del popup devono essere comprese tra 25 x 25 e 800 x 600 pixel.

Il popup viene inizialmente impostato dalla proprietà "default_popup" nella chiave "action" del file manifest.json. Se presente, questa proprietà deve puntare a un percorso relativo all'interno della directory dell'estensione. Può anche essere aggiornato dinamicamente per puntare 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, procedi nel seguente modo:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Se la proprietà tabId viene omessa, l'impostazione viene considerata globale. Le impostazioni specifiche della scheda hanno la priorità su quelle globali.

Stato attivato

Per impostazione predefinita, le azioni della barra degli strumenti sono abilitate (sono cliccabili) in ogni scheda. Puoi modificare questa impostazione predefinita impostando la proprietà default_state nella chiave action del manifest. Se default_state è impostato su "disabled", l'azione è disattivata per impostazione predefinita e deve essere attivata a livello di programmazione per essere cliccabile. Se default_state è impostato su "enabled" (valore predefinito), l'azione è abilitata e selezionabile per impostazione predefinita.

Puoi controllare lo stato in modo programmatico utilizzando i metodi action.enable() e action.disable(). Ciò influisce solo sull'invio o meno del popup (se presente) o dell'evento action.onClicked alla tua estensione; non influisce sulla presenza dell'azione nella barra degli strumenti.

Esempi

Gli esempi riportati di seguito mostrano alcuni modi comuni in cui vengono utilizzate le azioni nelle estensioni. Per provare questa API, installa l'esempio di API Action dal repository chrome-extension-samples.

Mostrare un popup

È normale che un'estensione mostri un popup quando l'utente fa clic sull'azione dell'estensione. Per implementare questa funzionalità 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>

Inserire uno script di contenuti al clic

Un pattern comune per le estensioni è quello di esporre la funzionalità principale utilizzando l'azione dell'estensione. Il seguente esempio 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 funzioni 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!');

Emulare le azioni con declarativeContent

Questo esempio mostra come la logica di 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);
  });
});

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)