action

Syntax

Der action-Schlüssel ist ein Objekt, das beliebige dieser Eigenschaften haben kann, alle optional:

browser_style Optional

Boolean. Optional, standardmäßig false.

Warnung: Setzen Sie browser_style nicht auf true: Die Unterstützung dafür wurde in Manifest V3 in Firefox 118 entfernt. Siehe Manifest V3 Migration für browser_style.

default_area Optional

String. Definiert den Teil des Browsers, in dem der Button zunächst platziert wird. Dies ist ein String, der einen von vier Werten 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 wird standardmäßig auf "menupanel" gesetzt. Firefox merkt sich die default_area-Einstellung für eine Erweiterung, auch wenn diese Erweiterung deinstalliert und anschließend neu 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 nicht ändern, nachdem sie installiert wurde, aber der Benutzer kann den Button möglicherweise mithilfe des integrierten Mechanismus zur Anpassung der Benutzeroberfläche des Browsers verschieben.

default_icon Optional

Object oder String. Verwenden Sie dies, um eines oder mehrere Symbole für die Aktion anzugeben. Das Symbol wird standardmäßig in der Browsersymbolleiste angezeigt. Symbole werden als URLs relativ zur manifest.json-Datei angegeben.

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 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 Symbole derselben Größe angeben. Siehe Auswahl der Symbolgrößen für weitere Leitlinien 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 mithilfe von <link>- und <script>-Elementen einbeziehen, genau wie eine normale Webseite. Darin muss jedoch <script> ein src-Attribut haben, um eine Datei zu laden. Verwenden Sie kein <script> mit eingebettetem Code, da Sie sonst einen verwirrenden Content-Security-Policy-Fehler erhalten. Anders als bei einer normalen Webseite kann auf im Popup ausgeführtes JavaScript auf alle WebExtension-APIs zugegriffen werden (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 die Maus darüber bewegt. Wenn der Button zur Menüleiste des Browsers hinzugefügt wird, wird dieser auch unter dem App-Symbol angezeigt. Dies ist eine lokalisierbare Eigenschaft.

theme_icons Optional

Array. Diese Eigenschaft erlaubt es Ihnen, je nach Erkennung eines dunklen oder hellen Textes durch Firefox unterschiedliche Symbole für Themen 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 Symbol verweist. Dieses Symbol wird angezeigt, wenn ein Thema mit dunklem Text aktiv ist (wie z.B. das Firefox Light Theme und, wenn kein default_icon angegeben ist, das Default Theme).

"light"

Eine URL, die auf ein Symbol verweist. Dieses Symbol wird angezeigt, wenn ein Thema mit hellem Text aktiv ist (wie z.B. das Firefox Dark Theme).

"size"

Die Größe der beiden Symbole in Pixeln.

Symbole 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-Symbol in default_icon angeben und eine Medienabfrage zu prefers-color-scheme verwenden, um das Symbol für helle und dunkle Themen 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 Beispiel für themenbasierte Symbole.

Auswahl der Symbolgrößen

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

• Das Symbol wird in der Browsersymbolleiste angezeigt. Ältere Versionen von Firefox unterstützten die Möglichkeit, das Symbol im Menübereich des Browsers zu platzieren (das Panel, das sich öffnet, wenn der Benutzer auf das "Hamburger"-Symbol klickt). In diesen Firefox-Versionen war das Menübereich-Symbol größer als das Symbol in der Symbolleiste.
• Auf einem hochauflösenden Bildschirm wie einem Retina-Display 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. Durch das Skalieren kann das Symbol verschwommen erscheinen. Daher ist es wichtig, die Symbolgrößen sorgfältig auszuwählen.

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

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

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

In Firefox:

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

Sie können Symbole genau anpassen, sowohl auf normalen als auch Retina-Displays, indem Sie drei Symboldateien bereitstellen und sie auf diese Weise angeben:

"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, wählt er das kleinste spezifizierte Symbol, das größer ist als die ideale Größe. Wenn alle Symbole kleiner als die ideale Größe sind, wird das größte spezifizierte Symbol ausgewählt.

Beispiel

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

Eine Aktion mit nur einem Symbol, in 2 Größen angegeben. Die Hintergrundskripte der Erweiterung können Click-Events empfangen, wenn der Benutzer auf das Symbol klickt, indem sie diesen Code verwenden:

browser.action.onClicked.addListener(handleClick);

"action": {
  "default_icon": {
    "16": "button/geo-16.png",
    "32": "button/geo-32.png"
  },
  "default_title": "Whereami?",
  "default_popup": "popup/geo.html"
}

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

Browser-Kompatibilität