chrome.browserAction

Beschreibung

Mithilfe von Browseraktionen können Sie Symbole in der Hauptsymbolleiste von Google Chrome rechts neben der Adressleiste platzieren. Neben dem Symbol kann eine Browseraktion eine Kurzinfo, ein Logo und ein Pop-up enthalten.

Verfügbarkeit

<ph type="x-smartling-placeholder"></ph> &amp;leq; MV2

In der folgenden Abbildung ist das mehrfarbige Quadrat rechts neben der Adressleiste das Symbol für ein Browseraktion. Unter dem Symbol befindet sich ein Pop-up-Fenster.

Wenn Sie ein Symbol erstellen möchten, das nicht immer aktiv ist, verwenden Sie statt eines Browsers eine Seitenaktion. Aktion ausführen.

Manifest

Registrieren Sie die Browseraktion wie folgt im Manifest der Erweiterung:

{
  "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 ein beliebiges Größensymbol zur Verwendung in Chrome angeben. Chrome wählt dann das nächstgelegene Symbol aus und skaliert es auf die richtige Größe an, um den 16-Dip-Bereich auszufüllen. Wenn jedoch keine genaue Größe angegeben wird, Skalierung kann dazu führen, dass das Symbol Details verliert oder unscharf erscheint.

Da Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5- oder 1,2-fach immer häufiger verwendet werden, wird empfohlen, mehrere Größen für Ihre Symbole bereitzustellen. Dadurch wird auch sichergestellt, geändert wird, müssen Sie nichts weiter tun, um verschiedene Symbole bereitzustellen!

Die alte Syntax zur Registrierung 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" }
  },
  ...
}

Bestandteile der Benutzeroberfläche

Eine Browseraktion kann ein Symbol, eine Kurzinfo, ein Logo und ein Pop-up enthalten.

Symbol

Die Browser-Aktionssymbole in Chrome sind 16 Grad (geräteunabhängige Pixel) breit und hoch. Größer Symbole werden an die Größe angepasst. Die besten Ergebnisse erzielen Sie jedoch mit einem quadratischen Symbol mit 16 Dip-Punkten.

Sie können das Symbol auf zwei Arten festlegen: über ein statisches Bild oder über das HTML5-Canvas-Element. Mit Für einfache Anwendungen sind statische Bilder einfacher. Sie können jedoch dynamischere Benutzeroberflächen erstellen, z. B. mit dem Canvas-Element.

Statische Bilder können in jedem Format vorliegen, das WebKit anzeigen kann, einschließlich BMP, GIF, ICO, JPEG oder PNG. Für entpackten Erweiterungen müssen die Bilder im PNG-Format vorliegen.

Verwenden Sie zum Festlegen des Symbols das Feld default_icon von default_icon im Manifest oder rufen Sie Methode browserAction.setIcon

Damit das Symbol richtig angezeigt wird, wenn die Bildschirmpixeldichte (Verhältnis size_in_pixel / size_in_dip) als 1, kann das Symbol als Bildersatz mit unterschiedlichen Größen definiert werden. Das eigentliche Bild für Display so aus, dass es am besten zur Pixelgröße von 16 Dip passt. Der Symbolsatz kann folgende Elemente enthalten: keine Größensymbole angeben, und Chrome wählt 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. Sie können gebietsspezifische Zeichenfolgen für die default_title; Weitere Informationen findest du unter Internationalisierung.

Badge

In Browseraktionen kann optional ein Logo angezeigt werden. Das ist ein Text, der über dem Symbol eingeblendet wird. Logos erleichtern es Ihnen, die Browseraktion so zu aktualisieren, dass nur wenige Informationen zum Status der Erweiterung.

Da der Platz für das Logo begrenzt ist, darf es maximal 4 Zeichen lang sein.

Legen Sie mit browserAction.setBadgeText den Text und die Farbe des Logos fest. browserAction.setBadgeBackgroundColor.

Wenn eine Browseraktion ein Pop-up-Fenster hat, wird dieses angezeigt, wenn der Nutzer auf das Symbol der Erweiterung klickt. Die Pop-up 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.

Wenn Sie Ihrer Browseraktion ein Pop-up hinzufügen möchten, 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 oder rufen Sie die Methode browserAction.setPopup-Methode.

Tipps

Beachten Sie die folgenden Richtlinien, um eine optimale visuelle Wirkung zu erzielen:

  • Verwenden Sie 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. Seite verwenden Aktionen.
  • Verwenden Sie große, farbenfrohe Symbole, die die Fläche von 16 × 16 dip optimal ausnutzen. Browseraktionssymbole etwas größer und schwerer erscheinen als Aktionssymbole für die Seite.
  • Versuchen Sie nicht, das monochrome Menüsymbol von Google Chrome zu imitieren. Das funktioniert nicht gut mit und Erweiterungen sollten sich ein wenig abheben.
  • Verwenden Sie Alpha-Transparenz, um Ihrem Symbol weiche Kanten hinzuzufügen. Da viele Nutzer Designs verwenden, Symbol sollte bei einer Vielzahl von Hintergrundfarben gut aussehen.
  • Animieren Sie Ihr Symbol nicht ständig. Das ist einfach nervig.

Beispiele

Einfache Beispiele für die Verwendung von Browseraktionen finden Sie unter examples/api/browserAction. -Verzeichnis. Weitere Beispiele und Hilfe zum Aufrufen des Quellcodes finden Sie unter Beispiele.

Typen

ColorArray

Typ

[Zahl, Zahl, Zahl, Zahl]

ImageDataType

Pixeldaten für ein Bild. Muss ein ImageData-Objekt sein. zum Beispiel aus einem canvas-Element.

Typ

ImageData

TabDetails

Chrome (ab Version 88)

Attribute

  • tabId

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

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Deaktiviert die Browseraktion für einen Tab.

Parameter

  • tabId

    Zahl optional

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

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

enable()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

Parameter

  • tabId

    Zahl optional

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

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

getBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Ruft die Hintergrundfarbe der Browseraktion ab.

Parameter

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result: ColorArray) => void

Gibt Folgendes zurück:

  • Promise&lt;ColorArray&gt;

    Chrome (ab Version 88)

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

getBadgeText()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

Ruft den Badge-Text der Browseraktion ab. Wenn kein Tab angegeben wird, wird der nicht tabulatorspezifische Logotext zurückgegeben.

Parameter

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result: string) => void

    • Ergebnis

      String

Gibt Folgendes zurück:

  • Promise&lt;string&gt;

    Chrome (ab Version 88)

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

getPopup()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

Parameter

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result: string) => void

    • Ergebnis

      String

Gibt Folgendes zurück:

  • Promise&lt;string&gt;

    Chrome (ab Version 88)

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

getTitle()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Ruft den Titel der Browseraktion ab.

Parameter

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (result: string) => void

    • Ergebnis

      String

Gibt Folgendes zurück:

  • Promise&lt;string&gt;

    Chrome (ab Version 88)

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

setBadgeBackgroundColor()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Legt die Hintergrundfarbe des Logos fest.

Parameter

  • Details

    Objekt

    • Farbe

      string | ColorArray

      Ein Array von vier Ganzzahlen im Bereich von 0 bis 255, aus denen die RGBA-Farbe des Logos besteht. Kann auch ein String mit einem CSS-Hexadezimalfarbwert sein. z. B. #FF0000 oder #F00 (rot). Rendert Farben mit voller Deckkraft.

    • tabId

      Zahl optional

      Beschränkt die Änderung auf das Auswählen eines bestimmten Tabs. Wird beim Schließen des Tabs automatisch zurückgesetzt.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

setBadgeText()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Legt den Badge-Text für die Browseraktion fest. Das Badge wird über dem Symbol angezeigt.

Parameter

  • Details

    Objekt

    • tabId

      Zahl optional

      Beschränkt die Änderung auf das Auswählen eines bestimmten Tabs. Wird beim Schließen des Tabs automatisch zurückgesetzt.

    • Text

      String optional

      Es kann eine beliebige Anzahl von Zeichen übergeben werden, aber nur etwa vier können in den Bereich passen. Wird ein leerer String ('') übergeben, wird der Logotext gelöscht. Wenn tabId angegeben und text null ist, wird der Text auf dem angegebenen Tab gelöscht und standardmäßig der globale Logotext verwendet.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

setIcon()

<ph type="x-smartling-placeholder"></ph> 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 eines Canvas-Elements oder als Dictionary aus einem dieser Elemente angegeben werden. Es muss entweder das Attribut path oder das Attribut imageData angegeben werden.

Parameter

  • Details

    Objekt

    • imageData

      ImageData | Objekt optional

      Entweder ein ImageData-Objekt oder ein Wörterbuch {size -> ImageData}, die ein festzulegendes Symbol darstellen. 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 Bildschirmgröße passen, scale entspricht, 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' entspricht 'details.imageData = {'16': foo}'.

    • Pfad

      string | Objekt optional

      Entweder ein relativer Bildpfad oder ein Wörterbuch {size -> relative image path} , der auf ein Symbol verweist, das Sie festlegen möchten. 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 Bildschirmgröße passen, scale entspricht, 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" entspricht 'details.path = {'16': foo}'

    • tabId

      Zahl optional

      Beschränkt die Änderung auf das Auswählen eines bestimmten Tabs. Wird beim Schließen des Tabs automatisch zurückgesetzt.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 116 und höher

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

setPopup()

<ph type="x-smartling-placeholder"></ph> 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 Aktionssymbol des Browsers klickt.

Parameter

  • Details

    Objekt

    • Pop-up

      String

      Der relative Pfad zur HTML-Datei, die in einem Pop-up angezeigt werden soll. Wenn der Wert auf einen leeren String festgelegt ist (''), wird kein Pop-up angezeigt.

    • tabId

      Zahl optional

      Beschränkt die Änderung auf das Auswählen eines bestimmten Tabs. Wird beim Schließen des Tabs automatisch zurückgesetzt.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

setTitle()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

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

Parameter

  • Details

    Objekt

    • tabId

      Zahl optional

      Beschränkt die Änderung auf das Auswählen eines bestimmten Tabs. Wird beim Schließen des Tabs automatisch zurückgesetzt.

    • Titel

      String

      Zeichenfolge, die die Browseraktion anzeigen soll, wenn der Mauszeiger darüber bewegt wird.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome (ab Version 88)

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

Ereignisse

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-Fenster enthält.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (tab: tabs.Tab) => void