chrome.action

Beschreibung

Verfügbarkeit

Manifest

Wenn Sie die chrome.action API verwenden möchten, geben Sie für "manifest_version" den Wert 3 an und fügen Sie den Schlüssel "action" in Ihre Manifestdatei ein.

{
  "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
  },
  ...
}

Der Schlüssel "action" (zusammen mit seinen untergeordneten Elementen) ist optional. Ist die Erweiterung nicht darin enthalten, wird sie trotzdem in der Symbolleiste angezeigt, damit Sie auf das Menü der Erweiterung zugreifen können. Aus diesem Grund empfehlen wir, immer mindestens die Schlüssel "action" und "default_icon" anzugeben.

Konzepte und Verwendung

Bestandteile der Benutzeroberfläche

Icon

Das Symbol ist das Hauptbild in der Symbolleiste für deine Erweiterung und wird durch den "default_icon"-Schlüssel im "action"-Schlüssel deines Manifests festgelegt. Symbole müssen 16 geräteunabhängige Pixel (DIPs) breit und hoch sein.

Der Schlüssel "default_icon" ist ein Wörterbuch der Größen für Bildpfade. Chrome verwendet diese Symbole, um die Bildgröße auszuwählen. Wenn keine genaue Übereinstimmung gefunden wird, wählt Chrome die am besten passende Option aus und skaliert sie für das Bild. Dies kann die Bildqualität beeinträchtigen.

Da Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5x oder 1,2x immer häufiger verwendet werden, empfehlen wir Ihnen, mehrere Größen für Ihre Symbole anzugeben. Dadurch wird Ihre Erweiterung auch auf mögliche Änderungen der Symbolanzeigegröße vorbereitet. Wenn Sie jedoch nur eine einzige Größe angeben, kann der Schlüssel "default_icon" auch auf einen String mit dem Pfad zu einem einzelnen Symbol anstelle eines Wörterbuchs gesetzt werden.

Sie können auch action.setIcon() aufrufen, um das Symbol der Erweiterung programmatisch festzulegen. Geben Sie dazu einen anderen Bildpfad oder ein dynamisch generiertes Symbol mithilfe des HTML-Canvas-Elements oder, falls die Einstellung über einen Erweiterungs-Service-Worker vorgenommen wird, die offscreen Canvas API an.

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}, () => { /* ... */ });

Bei gepackten Erweiterungen, die aus einer CRX-Datei installiert wurden, können Bilder in den meisten Formaten vorliegen, die von der Blink-Rendering-Engine angezeigt werden können, darunter PNG, JPEG, BMP und ICO. SVG wird nicht unterstützt. Für entpackte Erweiterungen müssen PNG-Bilder verwendet werden.

Kurzinfo (Titel)

Die Kurzinfo bzw. der Titel wird angezeigt, wenn der Nutzer den Mauszeiger auf das Symbol der Erweiterung in der Symbolleiste bewegt. Er ist auch in dem barrierefreien Text enthalten, der von Screenreadern vorgelesen wird, wenn die Schaltfläche hervorgehoben wird.

Die Standard-Kurzinfo wird mit dem Feld "default_title" des Schlüssels "action" in manifest.json festgelegt. Sie können sie auch programmatisch festlegen, indem Sie action.setTitle() aufrufen.

Badge

Für Aktionen kann optional ein „Badge“ angezeigt werden – ein Text, der über das Symbol gelegt wird. Auf diese Weise können Sie die Aktion so aktualisieren, dass eine kleine Anzahl von Informationen zum Status der Erweiterung angezeigt wird, z. B. ein Zähler. Das Logo hat eine Textkomponente und eine Hintergrundfarbe. Da der Platz begrenzt ist, empfehlen wir, maximal vier Zeichen zu verwenden.

Zum Erstellen eines Logos können Sie es programmatisch einrichten, indem Sie action.setBadgeBackgroundColor() und action.setBadgeText() aufrufen. Im Manifest gibt es keine Standardeinstellung für das Badge. Logo-Farbwerte können aus einem Array von vier Ganzzahlen zwischen 0 und 255 bestehen, aus denen die RGBA-Farbe des Logos besteht, oder ein String mit einem CSS-Farbe-Wert.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Pop-up

Das Pop-up einer Aktion wird angezeigt, wenn der Nutzer in der Symbolleiste auf die Aktionsschaltfläche der Erweiterung klickt. Das Pop-up-Fenster kann beliebige HTML-Inhalte enthalten und wird automatisch an den Inhalt angepasst. Das Pop-up muss zwischen 25 x 25 und 800 x 600 Pixel groß sein.

Das Pop-up wird anfangs durch das Attribut "default_popup" im Schlüssel "action" in der Datei manifest.json festgelegt. Falls dieses Attribut vorhanden ist, sollte es auf einen relativen Pfad innerhalb des Erweiterungsverzeichnisses verweisen. Er kann auch dynamisch mit der Methode action.setPopup() aktualisiert werden, sodass er auf einen anderen relativen Pfad verweist.

Anwendungsfälle

Status pro Tab

Erweiterungsaktionen können für jeden Tab einen anderen Status haben. Mit dem Attribut tabId in den Einstellungsmethoden der action API kannst du einen Wert für einen einzelnen Tab festlegen. Wenn du beispielsweise den Logotext für einen bestimmten Tab festlegen möchtest, kannst du Folgendes tun:

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

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

Wird das Attribut tabId weggelassen, wird die Einstellung als globale Einstellung behandelt. Tabspezifische Einstellungen haben Vorrang vor globalen Einstellungen.

Aktiviert

Standardmäßig sind Symbolleistenaktionen auf jedem Tab aktiviert (anklickbar). Dies lässt sich mit den Methoden action.enable() und action.disable() steuern. Dies wirkt sich nur darauf aus, ob das Pop-up-Ereignis (falls vorhanden) oder das action.onClicked-Ereignis an die Erweiterung gesendet wird. Es hat keinen Einfluss auf die Anzeige der Aktion in der Symbolleiste.

Beispiele

Die folgenden Beispiele zeigen einige gängige Verwendungsmöglichkeiten von Aktionen in Erweiterungen. Wenn Sie diese API ausprobieren möchten, installieren Sie das Action API-Beispiel aus dem Repository chrome-extension-sample.

Pop-up anzeigen

Es ist üblich, dass eine Erweiterung ein Pop-up anzeigt, wenn der Nutzer auf die Aktion der Erweiterung klickt. Wenn du dies in deiner eigenen Erweiterung implementieren möchtest, deklariere das Pop-up in deinem manifest.json und gib den Inhalt an, der von Chrome im Pop-up angezeigt werden soll.

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

Content-Script per Klick einfügen

Erweiterungen werden häufig nach dem Muster dargestellt, dass ihre Hauptfunktion über die Aktion der Erweiterung verfügbar gemacht wird. Das folgende Beispiel veranschaulicht dieses Muster. Wenn der Nutzer auf die Aktion klickt, fügt die Erweiterung ein Inhaltsskript in die aktuelle Seite ein. Das Content-Skript zeigt dann eine Benachrichtigung an, um zu überprüfen, ob alles erwartungsgemäß funktioniert.

// 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!');

Aktionen mit deklarativeContent emulieren

Dieses Beispiel zeigt, wie die Hintergrundlogik einer Erweiterung (a) eine Aktion standardmäßig deaktivieren und (b) declarativeContent verwenden kann, um die Aktion auf bestimmten Websites zu aktivieren.

// 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,
)