browser_action

Typ	`Object`
Erforderlich	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 eine Schaltfläche, die Ihre Erweiterung zur Symbolleiste des Browsers hinzufügt. Die Schaltfläche hat ein Symbol und kann optional ein Popup haben, dessen Inhalt mit 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 eine Schaltfläche zur Browser-Symbolleiste Ihrer Erweiterung hinzuzufügen. Wenn Sie ihn angeben, können Sie die Schaltfläche programmatisch mit der browserAction-API manipulieren.

Wenn Sie ein Popup bereitstellen, wird das Popup geöffnet, wenn der Benutzer auf die Schaltfläche klickt, und Ihr JavaScript, das im Popup ausgeführt wird, kann die Benutzerinteraktion mit diesem steuern. Wenn Sie kein Popup bereitstellen, wird beim Klicken auf die Schaltfläche ein Klickereignis an die Hintergrundskripte Ihrer Erweiterung gesendet.

Syntax

Der Schlüssel browser_action ist ein Objekt, das jede der folgenden Eigenschaften enthalten kann, alle optional:

Name	Typ	Beschreibung
`browser_style` Optional	`Boolean`	Optional, Standardwert ist `false`. Setzen Sie `browser_style` nicht auf true: dies wird in 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 angesehen werden. Wenn Sie Dimensionen festlegen, beachten Sie, dass dieses Stylesheet `box-sizing: border-box` anwendet (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 in einem Popup oder Seitenleisteninhalt einer Erweiterung auswählen. Dies ist normales Verhalten. Teile der Benutzeroberfläche im Browser können nicht ausgewählt werden. Es gibt jedoch zwei Möglichkeiten, um dieses Limit zu umgehen und es Ihren Benutzern zu ermöglichen, Text auszuwählen: Legen Sie `browser_style` auf `false` fest. Verwenden Sie CSS-Styling im Body Ihrer Seitenleiste oder des HTML-Popups, 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 die Schaltfläche zunächst platziert wird. Dies ist ein String, der einen von vier Werten annehmen kann: "navbar": Die Schaltfläche wird in der Haupt-Symbolleiste des Browsers neben der URL-Leiste platziert. "menupanel": Die Schaltfläche wird in einem Popup-Panel platziert. "tabstrip": Die Schaltfläche wird in der Symbolleiste platziert, die Zeilen des Browsers enthält. "personaltoolbar": Die Schaltfläche wird in der Lesezeichen-Symbolleiste platziert. Diese Eigenschaft wird nur in Firefox unterstützt. Diese Eigenschaft ist optional und hat als Standardwert "menupanel". Firefox merkt sich die Einstellung `default_area` für eine Erweiterung, auch wenn diese Erweiterung deinstalliert und später erneut installiert wurde. Um einen neuen Wert für `default_area` zu erzwingen, muss die ID der Erweiterung geändert werden. Eine Erweiterung kann den Ort der Schaltfläche nach der Installation nicht ändern, aber der Benutzer kann möglicherweise die Schaltfläche mit dem integrierten UI-Anpassungsmechanismus des Browsers verschieben.
`default_icon` Optional	`Object` oder `String`	Verwenden Sie dies, um ein oder mehrere Symbole für die Browser-Aktion anzugeben. Das Symbol wird standardmäßig in der Browser-Symbolleiste angezeigt. Symbole werden als URLs angegeben, die relativ zur manifest.json-Datei selbst sind. Sie können eine einzelne Symboldatei angeben, indem Sie hier einen String angeben: json `"default_icon": "path/to/geo.svg"` Um mehrere Symbole in verschiedenen Größen anzugeben, geben Sie hier ein Objekt an. Der Name jeder Eigenschaft ist die Höhe des Symbols in Pixeln und muss in einen Ganzzahl umwandelbar sein. Der Wert ist die URL. Beispiel: json `"default_icon": { "16": "path/to/geo-16.png", "32": "path/to/geo-32.png" }` Sie dürfen nicht mehrere Symbole mit denselben Größen spezifizieren. Siehe Auswahl von Symbolgröß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 enthalten, indem `<link>` und `<script>` Elemente verwendet werden, genau wie bei einer normalen Webseite. Allerdings muss `src` Attribut gesetzt sein, um eine Datei zu laden. Verwenden Sie nicht `<script>` mit eingebettetem Code, da Sie sonst einen verwirrenden Content Violation 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 die Schaltfläche, das angezeigt wird, wenn der Benutzer mit der Maus darüber fährt. Wenn die Schaltfläche dem Menü-Panel des Browsers hinzugefügt wird, wird dies auch unter dem App-Symbol angezeigt. Dies ist eine lokalisierbare Eigenschaft.
`theme_icons` Optional	`Array`	Diese Eigenschaft ermöglicht es Ihnen, verschiedene Symbole für Themen anzugeben, je nachdem, ob Firefox erkennt, dass das Thema dunklen oder hellen Text verwendet. Wenn diese Eigenschaft vorhanden ist, ist sie ein Array, das mindestens ein `ThemeIcons`-Objekt enthält. Ein `ThemeIcons`-Objekt enthält drei obligatorische Eigenschaften: `"dark"` Eine URL, die zu einem Symbol zeigt. Dieses Symbol wird angezeigt, wenn ein Thema mit dunklem Text aktiv ist (wie das Firefox Light-Theme und das Standardthema, wenn kein default_icon angegeben ist). `"light"` Eine URL, die zu einem Symbol zeigt. Dieses Symbol wird angezeigt, wenn ein Thema mit hellem Text aktiv ist (wie das Firefox Dark-Theme). `"size"` Die Größe der beiden Symbole in Pixeln. Symbole werden als URLs angegeben, die relativ zur manifest.json-Datei sind. Sie sollten 16x16 und 32x32 (für Retina-Display) `ThemeIcons` bereitstellen.

Auswahl von Symbolgrößen

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

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

Wenn der Browser kein Symbol der richtigen Größe in einer bestimmten Situation findet, wählt er die beste Übereinstimmung und skaliert es. Skalierung kann das Symbol unscharf erscheinen lassen, daher ist es wichtig, Symbolgrößen sorgfältig zu wählen.

Dafür gibt es zwei Hauptansätze. Sie können ein einzelnes Symbol als SVG-Datei bereitstellen, und es wird korrekt skaliert:

json

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

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

In Firefox:

Die Standardhöhe und -breite für Symbole in der Symbolleiste ist 16 * window.devicePixelRatio.
Die Standardhöhe und -breite für Symbole im Menü-Panel ist 32 * window.devicePixelRatio.

So können Sie Symbole angeben, die genau passen, sowohl auf normalen als auch auf Retina-Displays, indem Sie drei Symboldateien 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 genaue Übereinstimmung für die gewünschte Größe findet, wird es das kleinste angegebene Symbol auswählen, das größer als die ideale Größe ist. Sind alle Symbole kleiner als die ideale Größe, wählt es das größte angegebene Symbol.

Beispiel

json

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

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

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 Symbol, einem Titel und einem Popup. Das Popup wird angezeigt, wenn der Benutzer auf die Schaltfläche klickt.

Für eine einfache, aber vollständige Erweiterung, die eine Browser-Aktion verwendet, siehe die schrittweise Anleitung.

Browser-Kompatibilität

BCD tables only load in the browser

Syntax

Auswahl von Symbolgrößen

Beispiel

Browser-Kompatibilität

Siehe auch