browser.action

Beschreibung

Mit der chrome.action API können Sie das Symbol der Erweiterung in der Google Chrome-Symbolleiste steuern.

Die Aktionssymbole werden in der Symbolleiste des Browsers neben der Omnibox angezeigt. Nach der Installation werden sie im Menü „Erweiterungen“ (Puzzleteil-Symbol) angezeigt. Nutzer können das Symbol Ihrer Erweiterung an die Symbolleiste anpinnen.

Verfügbarkeit

Chrome 88 oder höher browser.* seit Chrome 148 MV3 oder höher

Manifest

Die folgenden Schlüssel müssen im Manifest deklariert werden, um diese API zu verwenden.

"action"

Wenn Sie die browser.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.

Hinweis : Jede Erweiterung hat ein Symbol in der Chrome-Symbolleiste, auch wenn der Schlüssel "action" nicht im Manifest enthalten ist.

{
  "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 die Erweiterung trotzdem in der Symbolleiste angezeigt, um Zugriff auf das Menü der Erweiterung zu ermöglichen. Daher empfehlen wir, immer mindestens die Schlüssel "action" und "default_icon" anzugeben.

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" des Manifests festgelegt. Symbole müssen 16 geräteunabhängige Pixel (DIPs) breit und hoch sein.

Der Schlüssel "default_icon" ist ein Wörterbuch 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 Größe aus und skaliert sie so, dass sie zum Bild passt. Dies 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, Symbole in mehreren Größen bereitzustellen. So ist Ihre Erweiterung auch für mögliche Änderungen der Anzeigegröße von Symbolen gerüstet. 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 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 mit dem HTML-Canvas-Element oder, wenn Sie es über einen Service Worker der Erweiterung festlegen, mit der 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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

Hinweis: Die action.setIcon() API ist für das Festlegen eines statischen Bildes vorgesehen. Verwenden Sie keine animierten Bilder für Ihre Symbole.

Bei gepackten Erweiterungen (aus einer CRX-Datei installiert) 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. Entpackte Erweiterungen müssen PNG-Bilder verwenden.

Kurzinfo (Titel)

Die Kurzinfo oder der Titel wird angezeigt, wenn der Nutzer den Mauszeiger auf das Symbol der Erweiterung in der Symbolleiste bewegt. Er ist auch im barrierefreien Text enthalten, der von Screenreadern vorgelesen wird, wenn der Button fokussiert wird.

Der 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

Aktionen können optional ein „Badge“ anzeigen – ein Text, der über dem Symbol eingeblendet 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 Badge hat eine Textkomponente und eine Hintergrundfarbe. Da der Platz begrenzt ist, empfehlen wir, für den Badge-Text maximal vier Zeichen zu verwenden.

Wenn Sie ein Badge erstellen möchten, legen Sie es programmatisch fest, indem Sie action.setBadgeBackgroundColor() und action.setBadgeText() aufrufen. Im Manifest ist keine Standardeinstellung für das Badge festgelegt. Die Farbwerte für das Badge können entweder ein Array mit vier Ganzzahlen zwischen 0 und 255 sein, die die RGBA-Farbe des Badges bilden, oder ein String mit einem CSS-Farbwert.

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

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

browser.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 kann beliebige HTML-Inhalte enthalten und wird automatisch an die Größe des Inhalts angepasst. Die Größe des Pop-ups muss zwischen 25 × 25 und 800 × 600 Pixel liegen.

Das Pop-up wird anfänglich durch das Attribut "default_popup" im Schlüssel "action" in der Datei manifest.json festgelegt. Wenn 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.

Hinweis: Das Ereignis action.onClicked wird nicht gesendet, wenn für die Erweiterungsaktion ein Pop-up angegeben wurde, das beim Klicken auf den aktuellen Tab angezeigt werden soll.

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 Badge-Text für einen bestimmten Tab festlegen möchten, gehen Sie so vor:

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

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

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

Aktivierungsstatus

Standardmäßig sind Symbolleistenaktionen auf jedem Tab aktiviert (anklickbar). Sie können diese Standardeinstellung ändern, indem Sie das Attribut 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" (Standard) gesetzt ist, ist die Aktion standardmäßig aktiviert und anklickbar.

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. Es hat keine Auswirkungen auf das Vorhandensein der Aktion in der Symbolleiste.

Beispiele

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

Pop-up anzeigen

Es ist üblich, dass eine Erweiterung ein Pop-up anzeigt, wenn der Nutzer auf die Aktion der Erweiterung klickt. Wenn Sie dies in Ihrer eigenen Erweiterung implementieren möchten, deklarieren Sie das Pop-up in Ihrer manifest.json und geben Sie die Inhalte an, die Chrome im Pop-up 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>

Inhaltsskript per Klick einfügen

Ein gängiges Muster für Erweiterungen besteht darin, ihre Hauptfunktion über die Aktion der Erweiterung bereitzustellen. 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 Inhaltsskript 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
browser.action.onClicked.addListener((tab) => {
  browser.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
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

Typen

OpenPopupOptions

Chrome 99 und höher browser.* seit Chrome 148

Attribute

• windowId

  number optional

  Die ID des Fensters, in dem das Aktions-Pop-up geöffnet werden soll. Wenn keine Angabe gemacht wird, wird standardmäßig das aktuell aktive Fenster verwendet.

TabDetails

Attribute

• tabId

  number optional

  Die ID des Tabs, dessen Status abgefragt werden soll. Wenn kein Tab angegeben ist, wird der nicht tabspezifische Status zurückgegeben.

UserSettings

Chrome 91 und höher browser.* seit Chrome 148

Die Sammlung der vom Nutzer angegebenen Einstellungen im Zusammenhang mit der Aktion einer Erweiterung.

Attribute

• isOnToolbar

  boolean

  Gibt an, ob das Aktionssymbol der Erweiterung in der Symbolleiste auf oberster Ebene des Browserfensters sichtbar ist, d.h. ob die Erweiterung vom Nutzer „angepinnt“ wurde.

UserSettingsChange

Chrome 130 und höher browser.* seit Chrome 148

Attribute

• isOnToolbar

  Boolesch optional

  Gibt an, ob das Aktionssymbol der Erweiterung in der Symbolleiste auf oberster Ebene des Browserfensters sichtbar ist, d.h. ob die Erweiterung vom Nutzer „angepinnt“ wurde.

Methoden

disable()

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

Deaktiviert die Aktion für einen Tab.

Parameter

• tabId

  number optional

  Die ID des Tabs, für den Sie die Aktion ändern möchten.

Ausgabe

• Promise<void>

enable()

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

Aktiviert die Aktion für einen Tab. Aktionen sind standardmäßig aktiviert.

Parameter

• tabId

  number optional

  Die ID des Tabs, für den Sie die Aktion ändern möchten.

Ausgabe

• Promise<void>

getBadgeBackgroundColor()

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

Ruft die Hintergrundfarbe der Aktion ab.

Parameter

• Details

  TabDetails

Ausgabe

• Promise<extensionTypes.ColorArray>

getBadgeText()

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

Ruft den Badge-Text der Aktion ab. Wenn kein Tab angegeben ist, wird der nicht tabspezifische Badge-Text zurückgegeben. Wenn displayActionCountAsBadgeText aktiviert ist, wird ein Platzhaltertext zurückgegeben, es sei denn, die Berechtigung declarativeNetRequestFeedback ist vorhanden oder es wurde ein tabspezifischer Badge-Text angegeben.

Parameter

• Details

  TabDetails

Ausgabe

• Promise<string>

getBadgeTextColor()

Chrome 110 und höher browser.* seit Chrome 148

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

Ruft die Textfarbe der Aktion ab.

Parameter

• Details

  TabDetails

Ausgabe

• Promise<extensionTypes.ColorArray>

getPopup()

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

Ruft das HTML-Dokument ab, das als Pop-up für diese Aktion festgelegt ist.

Parameter

• Details

  TabDetails

Ausgabe

• Promise<string>

getTitle()

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

Ruft den Titel der Aktion ab.

Parameter

• Details

  TabDetails

Ausgabe

• Promise<string>

getUserSettings()

Chrome 91 und höher browser.* seit Chrome 148

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

Gibt die vom Nutzer angegebenen Einstellungen für die Aktion einer Erweiterung zurück.

Ausgabe

• Promise<UserSettings>

isEnabled()

Chrome 110 und höher browser.* seit Chrome 148

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

Gibt an, ob die Erweiterungsaktion für einen Tab aktiviert ist (oder global, wenn kein tabId angegeben ist). Aktionen, die nur mit declarativeContent aktiviert werden, geben immer „false“ zurück.

Parameter

• tabId

  number optional

  Die ID des Tabs, für den Sie den Aktivierungsstatus prüfen möchten.

Ausgabe

• Promise<boolean>

openPopup()

Chrome 127 und höher browser.* seit Chrome 148

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

Öffnet das Pop-up der Erweiterung. Zwischen Chrome 118 und Chrome 126 ist dies nur für Erweiterungen verfügbar, die über Richtlinien installiert wurden.

Parameter

• Optionen

  OpenPopupOptions optional

  Gibt Optionen zum Öffnen des Pop-ups an.

Ausgabe

• Promise<void>

setBadgeBackgroundColor()

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

Legt die Hintergrundfarbe für das Logo fest.

Parameter

• Details

  Objekt

  • Farbe

    string | ColorArray

    Ein Array mit vier Ganzzahlen im Bereich [0,255], die die RGBA-Farbe des Badges bilden. Undurchsichtiges Rot ist beispielsweise [255, 0, 0, 255]. Kann auch ein String mit einem CSS-Wert sein, wobei undurchsichtiges Rot #FF0000 oder #F00 ist.

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

Ausgabe

• Promise<void>

setBadgeText()

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

Legt den Text für das Aktionslogo fest. Das Badge wird über dem Symbol angezeigt.

Parameter

• Details

  Objekt

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

  • Text

    String optional

    Es kann eine beliebige Anzahl von Zeichen übergeben werden, aber nur etwa vier passen in den Bereich. Wenn ein leerer String ('') übergeben wird, wird der Badge-Text gelöscht. Wenn tabId angegeben ist und text null ist, wird der Text für den angegebenen Tab gelöscht und standardmäßig der globale Badge-Text verwendet.

Ausgabe

• Promise<void>

setBadgeTextColor()

Chrome 110 und höher browser.* seit Chrome 148

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

Legt die Textfarbe für das Logo fest.

Parameter

• Details

  Objekt

  • Farbe

    string | ColorArray

    Ein Array mit vier Ganzzahlen im Bereich [0,255], die die RGBA-Farbe des Badges bilden. Undurchsichtiges Rot ist beispielsweise [255, 0, 0, 255]. Kann auch ein String mit einem CSS-Wert sein, wobei undurchsichtiges Rot #FF0000 oder #F00 ist. Wenn Sie diesen Wert nicht festlegen, wird automatisch eine Farbe ausgewählt, die sich von der Hintergrundfarbe des Logos abhebt, damit der Text sichtbar ist. Farben mit Alphawerten, die 0 entsprechen, werden nicht festgelegt und geben einen Fehler zurück.

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

Ausgabe

• Promise<void>

setIcon()

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

Legt das Symbol für die Aktion fest. Das Symbol kann entweder als Pfad zu einer Bilddatei oder als Pixeldaten aus einem Canvas-Element oder als Wörterbuch mit einem dieser beiden Elemente angegeben werden. Es muss entweder die Property path oder die Property imageData angegeben werden.

Parameter

• Details

  Objekt

  • imageData

    ImageData | Objekt optional

    Entweder ein ImageData-Objekt oder ein Wörterbuch {size -> ImageData}, das das festzulegende Symbol darstellt. Wenn das Symbol als Wörterbuch angegeben ist, wird das zu verwendende Bild je nach Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmeinheit passen, scale beträgt, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Hinweis: „details.imageData = foo“ entspricht „details.imageData = {'16': foo}“.

  • Pfad

    String | Objekt optional

    Entweder ein relativer Bildpfad oder ein Wörterbuch {size -> relative image path}, das auf das festzulegende Symbol verweist. Wenn das Symbol als Wörterbuch angegeben ist, wird das zu verwendende Bild je nach Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmeinheit passen, scale beträgt, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Beachten Sie, dass „details.path = foo“ „details.path = {'16': foo}“ entspricht.

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

Ausgabe

• Promise<void>

  Chrome 96+ browser.* seit Chrome 148

setPopup()

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

Legt das HTML-Dokument fest, das als Pop-up geöffnet werden soll, wenn der Nutzer auf das Symbol der Aktion klickt.

Parameter

• Details

  Objekt

  • Pop-up

    String

    Der relative Pfad zur HTML-Datei, die in einem Pop-up angezeigt werden soll. Wenn die Richtlinie auf einen leeren String ('') gesetzt ist, wird kein Pop-up angezeigt.

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

Ausgabe

• Promise<void>

setTitle()

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

Legt den Titel der Aktion fest. Dieser wird in der Kurzinfo angezeigt.

Parameter

• Details

  Objekt

  • tabId

    number optional

    Die Änderung wird nur angewendet, wenn ein bestimmter Tab ausgewählt ist. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.

  • Titel

    String

    Der String, der angezeigt werden soll, wenn der Mauszeiger auf die Aktion bewegt wird.

Ausgabe

• Promise<void>

Ereignisse

onClicked

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

Wird ausgelöst, wenn auf ein Aktionssymbol geklickt wird. Dieses Ereignis wird nicht ausgelöst, wenn die Aktion ein Pop-up hat.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (tab: tabs.Tab) => void

  • Tabulatortaste

    tabs.Tab

onUserSettingsChanged

Chrome 130 und höher browser.* seit Chrome 148

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

Wird ausgelöst, wenn sich die vom Nutzer angegebenen Einstellungen für die Aktion einer Erweiterung ändern.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (change: UserSettingsChange) => void

  • Ändern

    UserSettingsChange