Beschreibung
Mit Browseraktionen können Sie Symbole in der Hauptsymbolleiste von Google Chrome rechts neben der Adressleiste platzieren. Neben dem Symbol kann eine Browseraktion auch eine Kurzinfo, ein Badge und ein Pop-up umfassen.
Verfügbarkeit
In der folgenden Abbildung ist das mehrfarbige Quadrat rechts neben der Adressleiste das Symbol für eine Browseraktion. Unter dem Symbol befindet sich ein Pop-up-Fenster.
Wenn Sie ein Symbol erstellen möchten, das nicht immer aktiv ist, verwenden Sie eine Seitenaktion anstelle einer Browseraktion.
Manifest
Registrieren Sie die Browseraktion im Erweiterungsmanifest so:
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
Sie können für Chrome ein beliebiges Größensymbol angeben. Chrome wählt dann das passende Symbol aus und skaliert es auf die entsprechende Größe, um den 16-Dip-Bereich zu füllen. Wird jedoch keine genaue Größe angegeben, kann diese Skalierung dazu führen, dass das Symbol an Details verloren geht oder unscharf wirkt.
Da Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5x oder 1,2x immer häufiger verwendet werden, sollten Sie mehrere Größen für Symbole bereitstellen. So ist auch sichergestellt, dass Sie keine weiteren Symbole erstellen müssen, falls sich die Größe der Anzeige ändern sollte.
Die alte Syntax zum Registrieren des Standardsymbols wird weiterhin unterstützt:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
Teile der Benutzeroberfläche
Eine Browseraktion kann ein Symbol, eine Kurzinfo, ein Badge und ein Pop-up haben.
Icon
Die Browser-Aktionssymbole in Chrome sind 16 (geräteunabhängige Pixel) breit und hoch. Größere Symbole werden an die Größe angepasst. Um optimale Ergebnisse zu erzielen, sollten Sie jedoch ein quadratisches Symbol mit 16 Dip verwenden.
Sie haben zwei Möglichkeiten, das Symbol festzulegen: mit einem statischen Bild oder mit dem HTML5-Canvas-Element. Statische Bilder sind für einfache Anwendungen einfacher zu verwenden. Mit dem Canvas-Element können Sie jedoch dynamischere UIs erstellen, z. B. eine flüssige Animation.
Statische Bilder können in jedem Format vorliegen, das WebKit anzeigen kann, einschließlich BMP, GIF, ICO, JPEG oder PNG. Bei entpackten Erweiterungen müssen Bilder im PNG-Format vorliegen.
Verwenden Sie zum Festlegen des Symbols das Feld default_icon von default_icon im Manifest oder rufen Sie die Methode browserAction.setIcon
auf.
Damit das Symbol richtig angezeigt wird, wenn die Bildschirmpixeldichte (Verhältnis size_in_pixel / size_in_dip
) von 1 abweicht, kann das Symbol als Gruppe von Bildern mit unterschiedlichen Größen definiert werden. Das tatsächliche Bild, das angezeigt werden soll, wird aus dem Satz ausgewählt, der am besten zur Pixelgröße von 16 Punkten passt. Der Symbolsatz kann beliebige Größensymbole enthalten. Chrome wählt dann das am besten geeignete aus.
Kurzinfo
Verwenden Sie zum Festlegen der Kurzinfo das Feld default_title von default_title im Manifest oder rufen Sie die Methode browserAction.setTitle
auf. Für das Feld default_title können Sie länderspezifische Strings angeben. Weitere Informationen finden Sie unter Internationalisierung.
Badge
Bei Browseraktionen kann optional ein Badge angezeigt werden. Das ist Text, der über das Symbol gelegt wird. Durch Badges lässt sich die Browseraktion ganz einfach aktualisieren, sodass nur eine kleine Information zum Status der Erweiterung angezeigt wird.
Da der Platz auf dem Badge begrenzt ist, darf es maximal 4 Zeichen umfassen.
Legen Sie den Text und die Farbe des Logos mit browserAction.setBadgeText
bzw. browserAction.setBadgeBackgroundColor
fest.
Pop-up
Wenn eine Browseraktion ein Pop-up enthält, wird dieses angezeigt, wenn der Nutzer auf das Symbol der Erweiterung klickt. Das Pop-up-Fenster kann beliebige HTML-Inhalte enthalten und wird automatisch an den Inhalt angepasst. Das Pop-up-Fenster darf nicht kleiner als 25 x 25 und nicht größer als 800 x 600 sein.
Um Ihrer Browseraktion ein Pop-up hinzuzufügen, erstellen Sie eine HTML-Datei mit dem Inhalt des Pop-ups. Geben Sie die HTML-Datei im Feld default_popup von default_popup im Manifest an oder rufen Sie die Methode browserAction.setPopup
auf.
Tipps
Beachten Sie die folgenden Richtlinien, um eine optimale visuelle Wirkung zu erzielen:
- Verwende Browseraktionen für Funktionen, die auf den meisten Seiten sinnvoll sind.
- Verwenden Sie Browseraktionen nicht für Funktionen, die nur für wenige Seiten sinnvoll sind. Verwenden Sie stattdessen Seitenaktionen.
- Verwenden Sie große, farbenfrohe Symbole, die den 16 x 16 Dip-Bereich optimal nutzen. Browseraktionssymbole sollten etwas größer und schwerer erscheinen als Seitenaktionssymbole.
- Versuchen Sie nicht, das einfarbige Menüsymbol von Google Chrome nachzuahmen. Das funktioniert nicht gut mit Themes, und jedenfalls sollten Erweiterungen ein bisschen hervorstechen.
- Richtig: Verwenden Sie Alphatransparenz, um Ihrem Symbol weiche Ränder hinzuzufügen. Weil viele Menschen Designs verwenden, sollte Ihr Symbol auf verschiedenen Hintergrundfarben gut aussehen.
- Animieren Sie das Symbol nicht ständig. Das ist nur ärgerlich.
Beispiele
Einfache Beispiele für die Verwendung von Browseraktionen finden Sie im Verzeichnis examples/api/browserAction. Weitere Beispiele und Hilfe zum Anzeigen des Quellcodes finden Sie unter Beispiele.
Typen
ColorArray
Typ
[Zahl, Zahl, Zahl]
ImageDataType
Pixel-Daten für ein Bild. Muss ein ImageData-Objekt sein, beispielsweise aus einem canvas
-Element.
Typ
ImageData
TabDetails
Attribute
-
tabId
Nummer optional
Die ID des Tabs, für den der Status abgefragt werden soll. Wenn kein Tab angegeben ist, wird der nicht tabulatorspezifische Status zurückgegeben.
Methoden
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
Deaktiviert die Browseraktion für einen Tab.
Parameter
-
tabId
Nummer optional
Die ID des Tabs, für den die Browseraktion geändert werden soll.
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
Aktiviert die Browseraktion für einen Tab. Die Standardeinstellung ist aktiviert.
Parameter
-
tabId
Nummer optional
Die ID des Tabs, für den die Browseraktion geändert werden soll.
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Ruft die Hintergrundfarbe der Browseraktion ab.
Parameter
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: ColorArray) => void
-
Ergebnis
-
Rückgabe
-
Promise<ColorArray>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
Ruft den Badgetext der Browseraktion ab. Wenn kein Tab angegeben ist, wird der nicht tabulatorspezifische Badgetext zurückgegeben.
Parameter
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: string) => void
-
Ergebnis
String
-
Rückgabe
-
Versprechen<string>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Ruft das HTML-Dokument ab, das als Pop-up für diese Browseraktion festgelegt ist.
Parameter
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: string) => void
-
Ergebnis
String
-
Rückgabe
-
Versprechen<string>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Ruft den Titel der Browseraktion ab.
Parameter
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: string) => void
-
Ergebnis
String
-
Rückgabe
-
Versprechen<string>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Hier legen Sie die Hintergrundfarbe des Logos fest.
Parameter
-
Details
Objekt
-
Farbe
String | ColorArray
Ein Array von vier Ganzzahlen im Bereich 0–255, aus denen die RGBA-Farbe des Logos besteht. Kann auch ein String mit einem hexadezimalen CSS-Farbwert sein, z. B.
#FF0000
oder#F00
(Rot). Gibt Farben mit voller Deckkraft wieder. -
tabId
Nummer optional
Begrenzt die Änderung auf die Auswahl eines bestimmten Tabs. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.
-
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
Legt den Badgetext für die Browseraktion fest. Das Logo wird über dem Symbol angezeigt.
Parameter
-
Details
Objekt
-
tabId
Nummer optional
Begrenzt die Änderung auf die Auswahl eines bestimmten Tabs. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.
-
Text
String optional
Es kann eine beliebige Anzahl von Zeichen übergeben werden, aber nur etwa vier passen in den Bereich. Wird ein leerer String (
''
) übergeben, wird der Badgetext gelöscht. WenntabId
angegeben ist undtext
den Wert null hat, wird der Text für den angegebenen Tab gelöscht und als Standard für das allgemeine Badge verwendet.
-
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
Legt das Symbol für die Browseraktion fest. Das Symbol kann als Pfad zu einer Bilddatei, als Pixeldaten aus einem Canvas-Element oder als Wörterbuch eines dieser Elemente angegeben werden. Es muss entweder die Property path
oder die Property imageData
angegeben werden.
Parameter
-
Details
Objekt
-
imageData
ImageData | Objekt optional
Entweder ein ImageData-Objekt oder ein Wörterbuch {size -> ImageData}, das ein festzulegendes Symbol darstellt. Wenn das Symbol als Wörterbuch angegeben ist, wird das verwendete Bild abhängig von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmbereichseinheit passen,
scale
ist, wird ein Bild mit der Größescale
* n ausgewählt, wobei n die Größe des Symbols auf der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Beachten Sie, dass "details.imageData = foo" äquivalent zu "details.imageData = {'16': foo}" ist. -
Pfad
String | Objekt optional
Entweder ein relativer Bildpfad oder ein Wörterbuch {size -> relativer Bildpfad}, der auf ein festzulegendes Symbol verweist. Wenn das Symbol als Wörterbuch angegeben ist, wird das verwendete Bild abhängig von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmbereichseinheit passen,
scale
ist, wird ein Bild mit der Größescale
* n ausgewählt, wobei n die Größe des Symbols auf der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Beachten Sie, dass „details.path = foo“ äquivalent zu 'details.path = {'16': foo}' ist. -
tabId
Nummer optional
Begrenzt die Änderung auf die Auswahl eines bestimmten Tabs. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.
-
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 116 oder höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
Legt fest, dass das HTML-Dokument als Pop-up geöffnet wird, wenn der Nutzer auf das Browser-Aktionssymbol klickt.
Parameter
-
Details
Objekt
-
Pop-up
String
Der relative Pfad zur HTML-Datei, die in einem Pop-up-Fenster angezeigt werden soll. Wenn der Wert auf den leeren String (
''
) gesetzt ist, wird kein Pop-up-Fenster angezeigt. -
tabId
Nummer optional
Begrenzt die Änderung auf die Auswahl eines bestimmten Tabs. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.
-
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
Legt den Titel der Browseraktion fest. Dieser Titel wird in der Kurzinfo angezeigt.
Parameter
-
Details
Objekt
-
tabId
Nummer optional
Begrenzt die Änderung auf die Auswahl eines bestimmten Tabs. Wird automatisch zurückgesetzt, wenn der Tab geschlossen wird.
-
Titel
String
Die Zeichenfolge, die die Browseraktion anzeigen soll, wenn die Maus darüber bewegt wird.
-
-
callback
Funktion optional
Chrome 67 oder höherDer Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 88 und höherPromise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.
Veranstaltungen
onClicked
chrome.browserAction.onClicked.addListener(
callback: function,
)
Wird ausgelöst, wenn auf ein Browseraktionssymbol geklickt wird Wird nicht ausgelöst, wenn die Browseraktion ein Pop-up enthält.