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 Symbolleiste 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 in Manifest V3-Erweiterungen durch action ersetzt.

Sie müssen diesen Schlüssel angeben, um einen Button in der Browser-Symbolleiste in Ihre Erweiterung aufzunehmen. Wenn angegeben, 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 ausgeführt wird, kann die Interaktion des Benutzers damit behandeln. Wenn Sie kein Popup bereitstellen, wird ein Klick-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 Eigenschaften haben kann, alle optional:

Name Typ Beschreibung
browser_style
Optional 		Boolean

Optional, standardmäßig false.

Setzen Sie browser_style nicht auf true: Es wird ab Manifest V3, beginnend mit Firefox 118, 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. Wenn Abmessungen festgelegt werden, beachten Sie, dass dieses Stylesheet box-sizing: border-box festlegt (siehe box-sizing).

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

Die latest-download Beispielerweiterung verwendet browser_style in ihrem Popup.

Hinweis: Wenn Sie browser_style auf true setzen, können Benutzer in einer Erweiterung kein Text im Popup- oder Sidebar-Inhalt auswählen. Dies ist normales Verhalten. Sie können keine Teile der Benutzeroberfläche im Browser auswählen. Es gibt jedoch zwei Möglichkeiten, dieses Einschränkungen zu umgehen, damit Benutzer Text auswählen können:

  1. Setzen Sie browser_style auf false.
  2. Verwenden Sie CSS-Styling im Body Ihres Sidebars oder Popups, 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 Hauptsymbolleiste des Browsers neben der URL-Leiste platziert.
  • "menupanel": Der Button wird in einem Popup-Panel platziert.
  • "tabstrip": Der Button wird in der Symbolleiste platziert, die die Browser-Tabs enthält.
  • "personaltoolbar": Der Button wird in der Lesezeichen-Symbolleiste platziert.

Diese Eigenschaft wird nur in Firefox unterstützt.

Diese Eigenschaft ist optional und standardmäßig auf "menupanel" gesetzt.

Firefox merkt sich die default_area-Einstellung einer Erweiterung, auch wenn diese Erweiterung 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 die Position des Buttons nach der Installation nicht ändern, aber der Benutzer kann möglicherweise den Button mit dem integrierten UI-Anpassungsmechanismus des Browsers verschieben.

default_icon
Optional		 Object oder String

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

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

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

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 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 keine mehreren Icons derselben Größe angeben.

Siehe Auswahl 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 mit <link> und <script> Elementen einbinden, genau wie eine normale Webseite. Allerdings muss src im <script>-Element angegeben werden, um eine Datei zu laden. Nutzen Sie nicht WebExtension APIs zugreifen (vorausgesetzt, die Erweiterung hat die entsprechenden Berechtigungen).

Dies ist eine lokalisierbare Eigenschaft.

default_title
Optional		 String

Tooltip für den Button, wird 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 angezeigt.

Dies ist eine lokalisierbare Eigenschaft.

theme_icons
Optional		 Array

Diese Eigenschaft ermöglicht es Ihnen, je nach der Erkennung durch Firefox, ob das Theme dunklen oder hellen Text verwendet, unterschiedliche Icons für Themes anzugeben.

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

"dark"
Eine URL, die auf ein Icon verweist. Dieses Icon wird angezeigt, wenn ein Theme verwendet wird, das dunklen Text verwendet (wie das Firefox Light-Theme und das Standard-Theme, wenn kein default_icon angegeben ist).
"light"
Eine URL, die auf ein Icon verweist. Dieses Icon wird angezeigt, wenn ein Theme verwendet wird, das hellen Text verwendet (wie das Firefox Dark-Theme).
"size"
Die Größe der beiden Icons in Pixeln.

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

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

Auswahl der Icon-Größen

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

  • Das Icon wird in der Browsersymbolleiste angezeigt. Ältere Versionen von Firefox unterstützten die Möglichkeit, das Icon im Menüpanel des Browsers zu platzieren (das Panel, das geöffnet wird, 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 Symbolleiste.
  • 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 für eine bestimmte Situation findet, wird er die beste Übereinstimmung wählen und skalieren. Skalieren kann das Icon unscharf erscheinen lassen, daher ist es wichtig, die Icon-Größen sorgfältig auszuwählen.

Es gibt zwei Hauptansätze dazu. 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 wird die beste Übereinstimmung auswählen.

In Firefox:

Daher können Sie Icons, die genau passen, sowohl für normale als auch für Retina-Displays bereitstellen, 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 findet, wird es das kleinste angegebene Icon wählen, das größer als die ideale Größe ist. Wenn alle Icons kleiner als die ideale Größe sind, wird es das größte angegebene Icon wählen.

Beispiel

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

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

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 die Erläuterungstutorial.

Browser-Kompatibilität

Siehe auch