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 mit HTML, CSS und JavaScript spezifiziert wird.

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

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

Wenn Sie ein Popup bereitstellen, wird das Popup geöffnet, wenn der Benutzer auf den Button klickt, und Ihr JavaScript, das im Popup läuft, kann die Interaktion des Benutzers damit verarbeiten. Wenn Sie kein Popup bereitstellen, wird bei einem Klick ein Ereignis an die Hintergrundskripte Ihrer Erweiterung gesendet, wenn der Benutzer auf den Button klickt.

Syntax

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

Name Typ Beschreibung
browser_style
Optional 		Boolean

Optional, Standardwert ist false.

Setzen Sie browser_style nicht auf true: es wird nicht in Manifest V3 unterstützt, beginnend mit Firefox 118. Siehe Manifest V3 Migration für browser_style.

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

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

Das latest-download Beispiel-Add-on verwendet browser_style in seinem Popup.

Hinweis: Wenn browser_style auf true gesetzt ist, können Benutzer keinen Text im Popup oder Seitenleisteninhalt einer Erweiterung auswählen. Dies ist ein normales Verhalten. Sie können keine Teile der UI im Browser auswählen. Sie können jedoch diese Einschränkung umgehen, um Ihren Benutzern das Auswählen von Text zu ermöglichen, und zwar auf zwei Arten:

  1. Setzen Sie browser_style auf false.
  2. Verwenden Sie CSS-Styling im Body des HTML für Ihre Seitenleiste oder Ihr Popup, um die 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 ursprünglich platziert wird. Dies ist ein String, der einen der vier Werte annehmen kann:

  • "navbar": der Button wird in der Haupt-Toolbar des Browsers, neben der URL-Leiste, platziert.
  • "menupanel": der Button wird in einem Popup-Panel platziert.
  • "tabstrip": der Button wird in der Toolbar platziert, 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 "menupanel".

Firefox merkt sich die default_area-Einstellung für eine Erweiterung, selbst wenn diese entfernt und anschließend wieder installiert wird. Um den Browser dazu zu bringen, einen neuen Wert für default_area zu akzeptieren, muss die ID der Erweiterung geändert werden.

Eine Erweiterung kann den Ort des Buttons nach der Installation nicht ändern, aber der Benutzer kann möglicherweise den Button mithilfe des integrierten 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 Toolbar des Browsers angezeigt.

Icons werden als URLs relativ zur Datei manifest.json angegeben.

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 Pixeln und muss in einen Integer konvertierbar sein. Der Wert ist die URL. Beispielsweise:

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

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

Siehe Auswahl von Icon-Größen für weitere Beratung zu diesem Thema.

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 enthalten, die mit <link> und <script> Elementen eingebunden werden, genau wie bei einer normalen Webseite. Allerdings muss <script> ein src Attribut haben, um eine Datei zu laden. Verwenden Sie kein <script> mit eingebettetem Code, da Sie sonst einen verwirrenden Fehler im Content Violation Policy erhalten.

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

Dies ist eine lokalisierbare Eigenschaft.

default_title
Optional		 String

Tooltip für den Button, angezeigt, wenn der Benutzer den Mauszeiger darüber bewegt. Wenn der Button zum Menüpanel des Browsers hinzugefügt wird, wird dies auch unter dem App-Icon gezeigt.

Dies ist eine lokalisierbare Eigenschaft.

theme_icons
Optional		 Array

Diese Eigenschaft ermöglicht es Ihnen, je nach Erkennung, ob Firefox ein Theme mit dunklem oder hellem Text verwendet, unterschiedliche Icons für Themes anzugeben.

Wenn diese Eigenschaft vorhanden ist, ist sie ein Array, das mindestens ein ThemeIcons-Objekt enthält. Ein ThemeIcons-Objekt enthält drei verpflichtende Eigenschaften:

"dark"
Eine URL, die auf ein Icon verweist. Dieses Icon wird angezeigt, wenn ein Theme mit dunklem Text aktiv ist (z. B. das Firefox Light-Theme und das Standard-Theme, falls 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 (z. B. das Firefox Dark-Theme).
"size"
Die Größe der beiden Icons in Pixel.

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

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

Auswahl von 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 Toolbar des Browsers angezeigt. Ältere Versionen von Firefox unterstützten die Möglichkeit, 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 das beste Übereinstimmung und skaliert es. Skalierung kann das Icon unscharf erscheinen lassen, 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, und es wird korrekt skaliert:

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

Alternativ können Sie mehrere Icons in verschiedenen Größen bereitstellen, und der Browser wählt die beste Übereinstimmung.

In Firefox:

So können Sie Icons angeben, die genau passen, sowohl auf normalen als auch auf Retina-Displays, indem Sie drei Icon-Dateien bereitstellen und sie wie folgt 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 exakte Übereinstimmung für die gewünschte Größe finden kann, wählt es das kleinste angegebene Icon aus, 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 mit nur einem Icon, in 2 verschiedenen Größen angegeben. Die Hintergrundskripte der Erweiterung können Klickereignisse empfangen, wenn der Benutzer auf das Icon klickt, indem sie Code wie diesen verwenden:

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 Schritt-für-Schritt-Tutorial.

Browser-Kompatibilität

Siehe auch