browser_action

Syntax

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

browser_style Optional

Boolean. Optional, standardmäßig false.

Warnung: Setzen Sie browser_style nicht auf true: es wird in Manifest V3 nicht unterstützt, beginnend mit Firefox 118. 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 der 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 Beispielerweiterung verwendet browser_style in ihrem Popup.

Hinweis: Das Setzen von browser_style auf true verhindert, dass Benutzer Text im Popup oder Seitenleisteninhalt einer Erweiterung auswählen. Dies ist normales Verhalten. Sie können keine Teile der Benutzeroberfläche im Browser auswählen. Sie können jedoch diese Einschränkung umgehen, um es Ihren Benutzern zu ermöglichen, Text auf zwei Arten auszuwählen:

1. Setzen Sie browser_style auf false.
2. Verwenden Sie CSS-Styling für den Body Ihres Seitenleisten- oder Popup-HTMLs, um die Textauswahl zu erlauben, 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 anfänglich platziert wird. Dies ist ein String, der einen von vier Werten annehmen kann:

• "navbar": Der Button wird in der Haupt-Toolbar des Browsers platziert, neben der URL-Leiste.
• "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. Sie ist optional und standardmäßig auf "menupanel" gesetzt. Firefox merkt sich die default_area Einstellung für eine Erweiterung, selbst wenn diese deinstalliert und erneut installiert wird. Um den Browser zu zwingen, einen neuen Wert anzuerkennen, muss die ID der Erweiterung geändert werden. Eine Erweiterung kann den Ort des Buttons nach der Installation nicht ändern, aber der Benutzer kann ihn mithilfe des eingebauten UI-Anpassungsmechanismus des Browsers verschieben.

default_icon Optional

Object oder String. Verwenden Sie dies, um eines 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 Manifest.json-Datei selbst angegeben.

Sie können eine einzelne 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 Pixel und muss in eine ganze Zahl konvertierbar 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 Auswählen von Icon-Größen für weitere Anleitungen.

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 unter Verwendung von <link> und <script> Elementen einbeziehen, genau wie eine normale Webseite. <script> Elemente müssen jedoch ein src Attribut haben, um eine Datei zu laden. Verwenden Sie <script> nicht mit eingebettetem Code, da Sie sonst einen verwirrenden Content Security Policy-Fehler erhalten.

Anders als in einer normalen Webseite kann JavaScript, das im Popup ausgeführt wird, auf alle WebExtension-APIs zugreifen (sofern die Erweiterung über die entsprechenden Berechtigungen verfügt). Dies ist eine lokalisierbare Eigenschaft.

default_title Optional

String. Tooltip für den Button, angezeigt, wenn der Benutzer die Maus darüber bewegt. Wenn der Button dem 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, verschiedene Icons für Themes anzugeben, je nachdem, ob Firefox erkennt, dass das Theme dunklen oder hellen Text verwendet. Wenn vorhanden, ist es ein Array, das mindestens ein ThemeIcons-Objekt enthält. Ein ThemeIcons-Objekt enthält drei verpflichtende Eigenschaften:

"dark"

Eine URL, die auf ein Icon zeigt. Dieses Icon wird angezeigt, wenn ein Theme verwendet wird, das dunklen Text verwendet (wie das Firefox Light Theme und, falls kein default_icon angegeben ist, das Standard-Theme).

"light"

Eine URL, die auf ein Icon zeigt. 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 Pixel.

Icons werden als URLs relativ zur Manifest.json-Datei angegeben. Sie sollten 16x16 und 32x32 (für Retina-Displays) ThemeIcons bereitstellen.

Hinweis: Alternativ können Sie ein SVG-Icon in default_icon angeben und eine Medienabfrage auf prefers-color-scheme verwenden, um das Icon für helle und dunkle Themes zu aktualisieren. Zum Beispiel:

css

#outside {
  fill: black;
}
#inside {
  fill: red;
}
@media (prefers-color-scheme: dark) {
  #outside {
    fill: white;
  }
  #inside {
    fill: black;
  }
}

Für weitere Informationen siehe das themed-icons Beispiel.

Auswählen von 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 Toolbar des Browsers 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 in einer gegebenen Situation kein Icon in der richtigen Größe finden kann, wählt er das am besten passende und skaliert es. Das Skalieren kann dazu führen, dass das Icon verschwommen erscheint, 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:

"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:

• Die Standardhöhe und -breite für Icons in der Toolbar beträgt 16 * window.devicePixelRatio.
• Die Standardhöhe und -breite für Icons im Menü-Panel beträgt 32 * window.devicePixelRatio.

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

"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, 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

"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 Klick-Ereignisse empfangen, wenn der Benutzer das Icon anklickt, mit Code wie diesem:

browser.browserAction.onClicked.addListener(handleClick);

"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 den Button anklickt.

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

• page_action
• sidebar_action
• Browser-Stile