action

Typ Object
Verpflichtend Nein
Manifest-Version 3 oder höher
Beispiel
json
"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 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 angegeben wird.

Dieser Schlüssel ersetzt browser_action in Manifest V3-Erweiterungen.

Sie müssen diesen Schlüssel angeben, um eine Browser-Symbolleistenschaltfläche in Ihre Erweiterung aufzunehmen. Wenn angegeben, können Sie die Schaltfläche programmatisch mit der action API manipulieren.

Wenn Sie ein Popup bereitstellen, wird dieses geöffnet, wenn der Benutzer auf die Schaltfläche klickt, und Ihr JavaScript, das im Popup ausgeführt wird, kann die Interaktion des Benutzers damit handhaben. Wenn Sie kein Popup bereitstellen, wird ein Klickereignis an die Hintergrundskripte Ihrer Erweiterung gesendet, wenn der Benutzer auf die Schaltfläche klickt.

Syntax

Der action-Schlüssel ist ein Objekt, das eine oder mehrere der folgenden Eigenschaften haben kann, alle optional:

Name Typ Beschreibung
browser_style
Optional
Veraltet
Boolean

Optional, Standardwert ist false.

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

default_area
Optional
String

Definiert den Bereich des Browsers, in dem die Schaltfläche initially platziert wird. Dies ist eine Zeichenfolge, die einen von vier Werten annehmen kann:

  • "navbar": Die Schaltfläche wird in der Hauptsymbolleiste des Browsers platziert, neben der URL-Leiste.
  • "menupanel": Die Schaltfläche wird in einem Popup-Fenster platziert.
  • "tabstrip": Die Schaltfläche wird in der Symbolleiste platziert, die die Browser-Tabs 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 standardmäßig auf "menupanel" gesetzt.

Firefox speichert die default_area-Einstellung für eine Erweiterung, selbst wenn diese Erweiterung deinstalliert und anschließend erneut installiert wird. Um den Browser zu zwingen, einen neuen Wert für default_area zu erkennen, muss die ID der Erweiterung geändert werden.

Eine Erweiterung kann den Standort der Schaltfläche nicht ändern, nachdem sie installiert wurde, aber der Benutzer kann möglicherweise die Schaltfläche mithilfe des integrierten UI-Anpassungsmechanismus 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 Browser-Symbolleiste angezeigt.

Symbole werden als URLs angegeben, die relativ zur manifest.json-Datei selbst sind.

Sie können eine einzelne Symbol-Datei angeben, indem Sie hier eine Zeichenfolge bereitstellen:

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

Um mehrere Symbole in unterschiedlichen 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 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 Symbole der gleichen Größen angeben.

Siehe Auswahl der 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 unter Verwendung von <link> und <script> Elementen einbeziehen, genau wie eine normale Webseite. Jedoch, <script> muss das src Attribut haben, um eine Datei zu laden. Verwenden Sie nicht <script> mit eingebettetem Code, da Sie eine verwirrende Inhaltsrichtlinienverletzung erhalten.

Anders als bei einer normalen Webseite kann JavaScript, das im Popup ausgeführt wird, 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 die Schaltfläche, das angezeigt wird, wenn der Benutzer den Mauszeiger darüber bewegt. Wenn die Schaltfläche zur Menüleiste 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, je nach dem, ob Firefox erkennt, dass das Thema dunklen oder hellen Text verwendet, verschiedene Symbole für Themen anzugeben.

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

"dark"
Eine URL, die auf ein Symbol zeigt. Dieses wird angezeigt, wenn ein Thema mit dunklem Text aktiv ist (wie das Firefox Light-Thema und das Standardthema, wenn kein default_icon angegeben ist).
"light"
Eine URL, die auf ein Symbol zeigt. Dieses wird angezeigt, wenn ein Thema mit hellem Text aktiv ist (wie zum Beispiel das Firefox Dark-Thema).
"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.

Auswahl der Symbolgrößen

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

  • Das Symbol wird in der Browser-Symbolleiste angezeigt. Ältere Versionen von Firefox unterstützten die Möglichkeit, das Symbol im Menüpanel des Browsers zu platzieren (dem Panel, das geöffnet wird, wenn der Benutzer auf das "Hamburger"-Symbol klickt). 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 in einer bestimmten Situation kein Symbol der richtigen Größe finden kann, wird die am besten passtende Möglichkeit gewählt und skaliert. Das Skalieren kann dafür sorgen, dass das Symbol verschwommen aussieht, daher ist es wichtig, die Symbolgrößen sorgfältig auszuwählen.

Es gibt zwei Hauptansätze dazu. 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 wird die am besten passende Wahl treffen.

In Firefox:

So können Sie Symbole, die auf normalen und Retina-Displays genau stimmen, angeben, indem Sie drei Symbol-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 exakte Übereinstimmung für die gewünschte Größe finden kann, wird das kleinste angegebene Symbol gewählt, das größer als die ideale Größe ist. Wenn alle Symbole kleiner als die ideale Größe sind, wird das größte angegebene Symbol gewählt.

Beispiel

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

Eine Aktion mit nur einem Symbol, angegeben in 2 Größen. Die Hintergrundskripte der Erweiterung können Klickereignisse empfangen, wenn der Benutzer auf das Symbol klickt, indem Sie folgenden Code verwenden:

js
browser.action.onClicked.addListener(handleClick);
json
"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 die Schaltfläche klickt.

Browser-Kompatibilität

BCD tables only load in the browser