chrome.browserAction

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

≤ MV2

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.

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

Chrome 88 und höher

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()

Versprechen 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Deaktiviert die Browseraktion für einen Tab.

Parameters

  • tabId

    Nummer optional

    Die ID des Tabs, für den die Browseraktion geändert werden soll.

  • callback

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

enable()

Versprechen 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Aktiviert die Browseraktion für einen Tab. Die Standardeinstellung ist aktiviert.

Parameters

  • tabId

    Nummer optional

    Die ID des Tabs, für den die Browseraktion geändert werden soll.

  • callback

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

getBadgeBackgroundColor()

Versprechen 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Ruft die Hintergrundfarbe der Browseraktion ab.

Parameters

Rückgaben

  • Promise<ColorArray>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

getBadgeText()

Versprechen 
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.

Parameters

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string)=>void

    • Ergebnis

      String

Rückgaben

  • Versprechen<string>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

getPopup()

Versprechen 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Ruft das HTML-Dokument ab, das als Pop-up für diese Browseraktion festgelegt ist.

Parameters

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string)=>void

    • Ergebnis

      String

Rückgaben

  • Versprechen<string>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

getTitle()

Versprechen 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Ruft den Titel der Browseraktion ab.

Parameters

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string)=>void

    • Ergebnis

      String

Rückgaben

  • Versprechen<string>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

setBadgeBackgroundColor()

Versprechen 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Hier legen Sie die Hintergrundfarbe des Logos fest.

Parameters

  • 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öher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

setBadgeText()

Versprechen 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Legt den Badgetext für die Browseraktion fest. Das Logo wird über dem Symbol angezeigt.

Parameters

  • 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. Wenn tabId angegeben ist und text 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öher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

setIcon()

Versprechen 
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.

Parameters

  • 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öße scale * 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öße scale * 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ückgaben

  • Promise<void>

    Chrome 116 oder höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

setPopup()

Versprechen 
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.

Parameters

  • 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öher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Andere Plattformen müssen Callbacks verwenden.

setTitle()

Versprechen 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Legt den Titel der Browseraktion fest. Dieser Titel wird in der Kurzinfo angezeigt.

Parameters

  • 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öher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 88 und höher

    Promise-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.

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (tab: tabs.Tab)=>void