browser_action

Typ Object
Verpflichtend Nein
Manifest-Version 2
Beispiel
json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html",
  "theme_icons": [{
    "light": "icons/geo-16-light.png",
    "dark": "icons/geo-16.png",
    "size": 16
  }, {
    "light": "icons/geo-32-light.png",
    "dark": "icons/geo-32.png",
    "size": 32
  }]
}

Eine Browser-Aktion ist ein Button, den Ihre Erweiterung zur Toolbar des Browsers hinzufügt. Der Button hat ein Icon und kann optional ein Popup haben, dessen Inhalt mittels HTML, CSS und JavaScript festgelegt wird.

Dieser Schlüssel wird in Manifest V3-Erweiterungen durch action ersetzt.

Sie müssen diesen Schlüssel angeben, um einen Button in der Browser-Toolbar in Ihre Erweiterung einzufügen. Wenn er angegeben ist, können Sie den Button programmatisch über die browserAction API manipulieren.

Wenn Sie ein Popup bereitstellen, öffnet sich dieses, wenn der Benutzer auf den Button klickt, und Ihr JavaScript, das im Popup ausgeführt wird, kann die Benutzerinteraktion damit steuern. Wenn Sie kein Popup bereitstellen, wird ein Klick-Ereignis an die Hintergrundskripte Ihrer Erweiterung gesendet, wenn der Benutzer auf den Button klickt.

Syntax

Der Schlüssel browser_action ist ein Objekt, das eine der folgenden, alle optionalen, Eigenschaften haben kann:

Name Typ Beschreibung
browser_style
Optional 		Boolean

Optional, Standardwert ist false.

Setzen Sie browser_style nicht auf true: Ab Firefox 118 wird dies in Manifest V3 nicht unterstützt. Siehe Manifest V3-Migration für browser_style.

In Firefox kann das Stylesheet unter chrome://browser/content/extension.css oder chrome://browser/content/extension-mac.css auf macOS eingesehen werden. Beachten Sie beim Festlegen von Dimensionen, dass dieses Stylesheet box-sizing: border-box setzt (siehe box-sizing).

Browser-Stile beschreibt die Klassen, die Sie auf Elemente im Popup anwenden können, um bestimmte Stile zu erhalten.

Die latest-download Beispiel-Erweiterung verwendet browser_style in ihrem Popup.

Hinweis: Wenn Sie browser_style auf true setzen, können Benutzer keinen Text im Popup oder in den Seitenleisteninhalten der Erweiterung auswählen. Dies ist ein normales Verhalten. Sie können keine Teile der Benutzeroberfläche im Browser auswählen. Sie können jedoch diese Einschränkung umgehen, indem Sie Ihren Benutzern das Auswählen von Text auf zwei Arten ermöglichen:

  1. Setzen Sie browser_style auf false.
  2. Verwenden Sie CSS-Styling für den Body Ihres Sidebars oder des HTML-Popups, um Textauswahl zu ermöglichen, indem Sie die Regel -moz-user-select mit einem Wert von all oder text hinzufügen.
default_area
Optional		 String

Definiert den Teil des Browsers, in dem der Button zunächst platziert wird. Dies ist ein String, der einen der vier Werte annehmen kann:

  • "navbar": Der Button wird in der Haupt-Browser-Toolbar neben der URL-Leiste platziert.
  • "menupanel": Der Button wird in einem Popup-Panel platziert.
  • "tabstrip": Der Button wird in der Toolbar platziert, die die Browser-Tabs enthält.
  • "personaltoolbar": Der Button wird in der Lesezeichen-Toolbar platziert.

Diese Eigenschaft wird nur in Firefox unterstützt.

Diese Eigenschaft ist optional und hat standardmäßig den Wert "menupanel".

Firefox speichert die default_area-Einstellung für eine Erweiterung, selbst wenn diese deinstalliert und später wieder installiert wird. Um den Browser zu zwingen, einen neuen Wert für default_area anzuerkennen, muss die ID der Erweiterung geändert werden.

Eine Erweiterung kann den Standort des Buttons nach der Installation nicht ändern, aber der Benutzer kann den Button möglicherweise über den eingebauten UI-Anpassungsmechanismus des Browsers verschieben.

default_icon
Optional		 Object oder String

Verwenden Sie dies, um ein oder mehrere Icons für die Browser-Aktion anzugeben. Das Icon wird standardmäßig in der Browser-Toolbar angezeigt.

Icons werden als URLs angegeben, die relativ zur manifest.json-Datei selbst sind.

Sie können eine einzelne Icon-Datei angeben, indem Sie hier einen String bereitstellen:

json
"default_icon": "path/to/geo.svg"

Um mehrere Icons in verschiedenen Größen anzugeben, geben Sie hier ein Objekt an. Der Name jeder Eigenschaft ist die Höhe des Icons in Pixel und muss in einen Integer umwandelbar sein. Der Wert ist die URL. Zum Beispiel:

json
    "default_icon": {
      "16": "path/to/geo-16.png",
      "32": "path/to/geo-32.png"
    }

Sie können nicht mehrere Icons derselben Größe angeben.

Siehe Wahl der Icon-Größen für weitere Hinweise dazu.

default_popup
Optional		 String

Der Pfad zu einer HTML-Datei, die die Spezifikation des Popups enthält.

Die HTML-Datei kann CSS- und JavaScript-Dateien einbinden mit <link> und <script> Elementen, genau wie eine normale Webseite. Jedoch muss <script> das src Attribut haben, um eine Datei zu laden. Verwenden Sie kein <script> mit eingebettetem Code, weil Sie sonst einen verwirrenden Content Security Policy-Fehler erhalten.

Im Gegensatz zu einer normalen Webseite kann JavaScript, das im Popup läuft, auf alle WebExtension-APIs zugreifen (natürlich vorausgesetzt, dass die Erweiterung die entsprechenden Berechtigungen hat).

Dies ist eine lokalisierbare Eigenschaft.

default_title
Optional		 String

Tooltip für den Button, der angezeigt wird, wenn der Benutzer mit der Maus über den Button fährt. Wenn der Button zum Menü-Panel des Browsers hinzugefügt wird, wird dieser Tooltip auch unter dem App-Icon angezeigt.

Dies ist eine lokalisierbare Eigenschaft.

theme_icons
Optional		 Array

Diese Eigenschaft erlaubt es Ihnen, verschiedene Icons für Themes anzugeben, je nachdem, ob Firefox erkennt, dass das Theme dunklen oder hellen Text verwendet.

Wenn diese Eigenschaft vorhanden ist, handelt es sich um ein Array, das mindestens ein ThemeIcons-Objekt enthält. Ein ThemeIcons-Objekt enthält drei zwingende Eigenschaften:

"dark"
Eine URL, die auf ein Icon verweist. Dieses Icon wird angezeigt, wenn ein Theme mit dunklem Text aktiv ist (wie das Firefox Light-Theme und das Standardtheme, wenn kein default_icon angegeben ist).
"light"
Eine URL, die auf ein Icon verweist. Dieses Icon wird angezeigt, wenn ein Theme mit hellem Text aktiv ist (wie das Firefox Dark-Theme).
"size"
Die Größe der beiden Icons in Pixel.

Icons werden als URLs angegeben, die relativ zur manifest.json-Datei sind.

Sie sollten 16x16 und 32x32 (für Retina-Displays) ThemeIcons bereitstellen.

Wahl der Icon-Größen

Das Icon der Browser-Aktion muss möglicherweise in verschiedenen Größen in unterschiedlichen Kontexten angezeigt werden:

  • Das Icon wird in der Browser-Toolbar angezeigt. Ältere Versionen von Firefox unterstützten die Option, das Icon im Menü-Panel des Browsers zu platzieren (das Panel, das sich öffnet, wenn der Benutzer auf das "Hamburger"-Icon klickt). In diesen Versionen von Firefox war das Icon im Menü-Panel größer als das Icon in der Toolbar.
  • Auf einem hochauflösenden Display wie einem Retina-Bildschirm müssen Icons doppelt so groß sein.

Wenn der Browser kein Icon in der richtigen Größe in einer bestimmten Situation finden kann, wählt er den am besten passenden und skaliert ihn. Skalierung kann dazu führen, dass das Icon verschwommen aussieht, daher ist es wichtig, die Icon-Größen sorgfältig auszuwählen.

Es gibt zwei Hauptansätze dafür. Sie können ein einzelnes Icon als SVG-Datei bereitstellen, das dann korrekt skaliert wird:

json
"default_icon": "path/to/geo.svg"

Alternativ können Sie mehrere Icons in unterschiedlichen Größen bereitstellen, und der Browser wird den am besten passenden auswählen.

In Firefox:

So können Sie Icons bereitstellen, die auf normalen und Retina-Displays genau passen, indem Sie drei Icon-Dateien bereitstellen und sie so angeben:

json
"default_icon": {
  "16": "path/to/geo-16.png",
  "32": "path/to/geo-32.png",
  "64": "path/to/geo-64.png"
}

Wenn Firefox keine genaue Übereinstimmung für die gewünschte Größe finden kann, wählt es das kleinste angegebene Icon, das größer als die ideale Größe ist. Wenn alle Icons kleiner als die ideale Größe sind, wählt es das größte angegebene Icon.

Beispiel

json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  }
}

Eine Browser-Aktion nur mit einem Icon, das in 2 verschiedenen Größen angegeben ist. Die Hintergrundskripte der Erweiterung können Klick-Ereignisse empfangen, wenn der Benutzer auf das Icon klickt, mit Code wie diesem:

js
browser.browserAction.onClicked.addListener(handleClick);
json
"browser_action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

Eine Browser-Aktion mit einem Icon, einem Titel und einem Popup. Das Popup wird angezeigt, wenn der Benutzer auf den Button klickt.

Für eine einfache, aber vollständige Erweiterung, die eine Browser-Aktion verwendet, siehe das Walkthrough-Tutorial.

Browser-Kompatibilität

Siehe auch