chrome.action

Descrizione

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. Quando non è inclusa, l'estensione viene comunque visualizzata nella barra degli strumenti per darti 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 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.

Perché i dispositivi con fattori di scala meno comuni, come 1,5x o 1,2x, stanno diventando sempre più comune, ti consigliamo di fornire più dimensioni per le icone. Anche questo protegge le tue estensioni in futuro da potenziali modifiche alle 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 della tua estensione in modo programmatico specificando un percorso dell'immagine diverso o fornendo un'icona generata dinamicamente tramite canvas HTML oppure, se l'impostazione è da un service worker di estensione, fuori schermo canvas.

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. Il formato 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 inclusa nel testo accessibile pronunciato dagli screen reader quando il pulsante diventa 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. Questo consente di aggiornare l'azione per visualizzare una piccola quantità di informazioni sullo stato dell'estensione, come un contatore. Il badge ha una 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 il numero action.setBadgeBackgroundColor() e action.setBadgeText(). Nel file manifest non è presente un'impostazione predefinita per il badge. Valori colore del badge può essere un array di quattro numeri interi compresi tra 0 e 255 che compongono il colore RGBA 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

Un popup di azione viene mostrato quando l'utente fa clic sul pulsante di azione dell'estensione nella barra degli strumenti. Il popup può includere tutti i contenuti HTML che preferisci e verrà ridimensionato automaticamente per adattarsi alle tue esigenze. i suoi contenuti. Le dimensioni del popup devono essere comprese tra 25 x 25 e 800 x 600 pixel.

Il popup è inizialmente impostato dalla proprietà "default_popup" nella chiave "action" nella manifest.json file. Se presente, questa proprietà deve puntare a un percorso relativo all'interno dell'estensione . Può anche essere aggiornata dinamicamente in modo da puntare a un percorso relativo diverso utilizzando action.setPopup().

Casi d'uso

Stato per scheda

Le azioni delle estensioni 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 imposta il testo del badge per una scheda specifica, procedi in questo 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 nella barra degli strumenti sono attivate (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

I seguenti esempi mostrano alcuni modi comuni di utilizzo delle azioni nelle estensioni. Per provare questa API, installa l'esempio dell'API Action da chrome-extension-samples repository Git.

Mostra 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>

Inserisci uno script di contenuti al clic

Un pattern comune per le estensioni è esporre la funzionalità principale utilizzando il parametro un'azione. L'esempio seguente dimostra 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 di verifica che tutto ha 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 in che modo la logica in background di un'estensione può (a) disattivare un'azione per impostazione predefinita e (b) utilizzare declarativeContent per consentire 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,
  callback?: function,
)

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

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

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

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

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

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

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

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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