chrome.action

Beschreibung

Verfügbarkeit

Manifest

Wenn Sie die chrome.action API verwenden möchten, geben Sie "manifest_version" als 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. Wenn sie nicht enthalten ist, wird Ihre Erweiterung weiterhin in der Symbolleiste angezeigt, um Zugriff auf das Menü der Erweiterung zu ermöglichen. Aus diesem Grund empfehlen wir, immer mindestens die Schlüssel "action" und "default_icon" einzuschließen.

Konzepte und Verwendung

Teile der Benutzeroberfläche

Symbol

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

Der Schlüssel "default_icon" ist ein Dictionary mit Größen und Bildpfaden. Chrome verwendet diese Symbole, um die zu verwendende Bildskalierung auszuwählen. Wenn keine genaue Übereinstimmung gefunden wird, wählt Chrome die nächstgelegene verfügbare aus und skaliert sie, damit sie in das Bild passt. Das kann sich auf die Bildqualität auswirken.

Da Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5-fach oder 1,2-fach immer häufiger werden, empfehlen wir, mehrere Größen für Ihre Symbole anzugeben. So ist Ihre Erweiterung auch für zukünftige Änderungen der Anzeigegröße von Symbolen gerüstet. Wenn Sie jedoch nur eine Größe angeben, kann der "default_icon"-Schlüssel auch auf einen String mit dem Pfad zu einem einzelnen Symbol anstelle eines Dictionary festgelegt werden.

Sie können auch action.setIcon() aufrufen, um das Symbol Ihrer Erweiterung programmatisch festzulegen. Geben Sie dazu einen anderen Bildpfad an oder stellen Sie ein dynamisch generiertes Symbol über das HTML-Canvas-Element oder, wenn Sie es über einen Erweiterungs-Service-Worker festlegen, über die Offscreen-Canvas-API bereit.

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 werden) 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 oder der Titel wird angezeigt, wenn der Nutzer den Mauszeiger auf das Symbol der Erweiterung in der Symbolleiste bewegt. Er wird auch im barrierefreien Text berücksichtigt, der von Screenreadern vorgelesen wird, wenn die Schaltfläche den Fokus erhält.

Der Standard-Kurzinfo-Text 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. So können Sie die Aktion aktualisieren, um eine kleine Menge an Informationen zum Status der Erweiterung anzuzeigen, z. B. einen Zähler. Das Symbol besteht aus einer Textkomponente und einer Hintergrundfarbe. Da der Platz begrenzt ist, empfehlen wir, für den Badgetext maximal vier Zeichen zu verwenden.

Um ein Logo zu erstellen, legen Sie es programmatisch fest, indem Sie action.setBadgeBackgroundColor() und action.setBadgeText() aufrufen. Im Manifest gibt es keine Standardeinstellung für das Symbol. Die Werte für die Badge-Farbe können entweder ein Array aus vier Ganzzahlen zwischen 0 und 255 sein, die die RGBA-Farbe des Badges bilden, oder ein String mit einem CSS-Farbwert.

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 die Größe der Inhalte angepasst. Die Größe des Pop-ups muss zwischen 25 × 25 und 800 × 600 Pixeln liegen.

Das Pop-up wird anfangs durch das Attribut "default_popup" im Schlüssel "action" in der Datei manifest.json festgelegt. Falls vorhanden, sollte diese Property auf einen relativen Pfad im Erweiterungsverzeichnis verweisen. Er kann auch dynamisch aktualisiert werden, um mit der Methode action.setPopup() auf einen anderen relativen Pfad zu verweisen.

Anwendungsfälle

Status pro Tab

Erweiterungsaktionen können für jeden Tab unterschiedliche Status haben. Wenn Sie einen Wert für einen einzelnen Tab festlegen möchten, verwenden Sie das Attribut tabId in den Einstellungsmethoden der action API. Wenn Sie beispielsweise den Badgetext für einen bestimmten Tab festlegen möchten, gehen Sie so vor:

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

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

Wenn die Property tabId weggelassen wird, wird die Einstellung als globale Einstellung behandelt. Tab-spezifische Einstellungen haben Vorrang vor globalen Einstellungen.

Status „Aktiviert“

Standardmäßig sind Symbolleistenaktionen auf jedem Tab aktiviert (anklickbar). Sie können diese Standardeinstellung ändern, indem Sie die Eigenschaft default_state im Schlüssel action des Manifests festlegen. Wenn default_state auf "disabled" gesetzt ist, ist die Aktion standardmäßig deaktiviert und muss programmatisch aktiviert werden, damit sie angeklickt werden kann. Wenn default_state auf "enabled" (Standardeinstellung) festgelegt ist, ist die Aktion standardmäßig aktiviert und klickbar.

Sie können den Status programmatisch mit den Methoden action.enable() und action.disable() steuern. Dies wirkt sich nur darauf aus, ob das Pop-up (falls vorhanden) oder das action.onClicked-Ereignis an Ihre Erweiterung gesendet wird. Die Präsenz der Aktion in der Symbolleiste wird dadurch nicht beeinflusst.

Beispiele

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

Pop-up anzeigen

Häufig wird ein Pop-up-Fenster angezeigt, wenn der Nutzer auf die Aktion der Erweiterung klickt. Wenn Sie dies in Ihrer eigenen Erweiterung implementieren möchten, deklarieren Sie das Pop-up-Fenster in Ihrem manifest.json und geben Sie die Inhalte an, die Chrome im Pop-up-Fenster anzeigen 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>

Inhaltskript bei Klick einfügen

Ein gängiges Muster für Erweiterungen besteht darin, die primäre Funktion über die Aktion der Erweiterung verfügbar zu machen. Das folgende Beispiel veranschaulicht dieses Muster. Wenn der Nutzer auf die Aktion klickt, fügt die Erweiterung ein Content-Script in die aktuelle Seite ein. Das Content-Script zeigt dann eine Benachrichtigung an, um zu bestätigen, dass alles wie erwartet funktioniert hat.

// 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 „declarativeContent“ emulieren

In diesem Beispiel wird gezeigt, 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,
): 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,
)