chrome.pageAction

refresh date: 2026-09-25 robots: noindex

Beschreibung

Mit der chrome.pageAction API können Sie Symbole in der Hauptsymbolleiste von Google Chrome rechts neben der Adressleiste platzieren. Seitenaktionen sind Aktionen, die auf der aktuellen Seite ausgeführt werden können, aber nicht auf allen Seiten anwendbar sind. Seitenaktionen werden ausgegraut, wenn sie inaktiv sind.

Verfügbarkeit

≤ MV2

Beispiele:

  • RSS-Feed dieser Seite abonnieren
  • Diashow mit den Fotos auf dieser Seite erstellen

Das RSS-Symbol im folgenden Screenshot stellt eine Seitenaktion dar, mit der Sie den RSS-Feed für die aktuelle Seite abonnieren können.

Ausgeblendete Seitenaktionen werden ausgegraut angezeigt. Der RSS-Feed unten ist beispielsweise ausgegraut, da du den Feed für die aktuelle Seite nicht abonnieren kannst:

Verwenden Sie stattdessen eine Browseraktion, damit Nutzer immer mit Ihrer Erweiterung interagieren können.

Manifest

Registrieren Sie die Seitenaktion im Manifest der Erweiterung so:

{
  "name": "My extension",
  ...
  "page_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
  },
  ...
}

Da Geräte mit weniger gängigen Skalierungsfaktoren wie 1,5-fach oder 1,2-fach immer häufiger werden, empfehlen wir, mehrere Größen für Ihre Symbole bereitzustellen. Chrome wählt das am besten passende Symbol aus und skaliert es, um den 16-dip-Bereich zu füllen. Außerdem müssen Sie so keine weiteren Symbole bereitstellen, falls sich die Anzeigegröße des Symbols ändert. Wenn der Größenunterschied jedoch zu groß ist, kann diese Skalierung dazu führen, dass das Symbol an Details verliert oder unscharf aussieht.

Die alte Syntax zum Registrieren des Standardsymbols wird weiterhin unterstützt:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Teile der Benutzeroberfläche

Wie Browseraktionen können auch Seitenaktionen ein Symbol, eine Kurzinfo und ein Pop-up haben, aber keine Badges. Außerdem können Seitenaktionen ausgegraut sein. Informationen zu Symbolen, Kurzinfos und Pop-ups finden Sie im Artikel zur Benutzeroberfläche für Browseraktionen.

Mit den Methoden pageAction.show und pageAction.hide können Sie eine Seitenaktion einblenden und ausgrauen. Standardmäßig wird eine Seitenaktion ausgegraut angezeigt. Wenn Sie es einblenden, geben Sie den Tab an, in dem das Symbol angezeigt werden soll. Das Symbol bleibt sichtbar, bis der Tab geschlossen wird oder eine andere URL angezeigt wird (z. B. weil der Nutzer auf einen Link klickt).

Tipps

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

  • Verwenden Sie Seitenaktionen für Funktionen, die nur für wenige Seiten sinnvoll sind.
  • Verwenden Sie keine Seitenaktionen für Funktionen, die für die meisten Seiten sinnvoll sind. Verwenden Sie stattdessen Browseraktionen.
  • Animieren Sie Ihr Symbol nicht ständig. Das ist einfach nur nervig.

Typen

ImageDataType

Pixeldaten für ein Bild. Muss ein ImageData-Objekt sein (z. B. aus einem canvas-Element).

Typ

ImageData

TabDetails

Chrome 88 oder höher

Attribute

  • tabId

    number optional

    Die ID des Tabs, dessen Status abgefragt werden soll. Wenn kein Tab angegeben ist, wird der nicht tabspezifische Status zurückgegeben.

Methoden

getPopup()

Promise 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

Parameter

  • Details

    TabDetails

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: string) => void

    • Ergebnis

      String

Ausgabe

  • Promise<string>

    Chrome 101 oder höher

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

getTitle()

Promise 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Ruft den Titel der Seitenaktion ab.

Parameter

  • Details

    TabDetails

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: string) => void

    • Ergebnis

      String

Ausgabe

  • Promise<string>

    Chrome 101 oder höher

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

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

Blendet die Seitenaktion aus. Ausgeblendete Seitenaktionen werden weiterhin in der Chrome-Symbolleiste angezeigt, sind aber ausgegraut.

Parameter

  • tabId

    Zahl

    Die ID des Tabs, für den Sie die Seitenaktion ändern möchten.

  • callback

    function optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 oder höher

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

setIcon()

Promise 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Legt das Symbol für die Seitenaktion fest. Das Symbol kann entweder als Pfad zu einer Bilddatei oder als Pixeldaten aus einem Canvas-Element oder als Wörterbuch mit einem dieser beiden Elemente angegeben werden. Es muss entweder die Property path oder die Property imageData angegeben werden.

Parameter

  • Details

    Objekt

    • iconIndex

      number optional

      Veraltet. Dieses Argument wird ignoriert.

    • imageData

      ImageData | Objekt optional

      Entweder ein ImageData-Objekt oder ein Wörterbuch {size -> ImageData}, das das festzulegende Symbol darstellt. Wenn das Symbol als Wörterbuch angegeben ist, wird das zu verwendende Bild je nach Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmeinheit passen, scale beträgt, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Hinweis: „details.imageData = foo“ entspricht „details.imageData = {'16': foo}“.

    • Pfad

      String | Objekt optional

      Entweder ein relativer Bildpfad oder ein Wörterbuch {size -> relative image path}, das auf das festzulegende Symbol verweist. Wenn das Symbol als Wörterbuch angegeben ist, wird das zu verwendende Bild je nach Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmeinheit passen, scale beträgt, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. Beachten Sie, dass „details.path = foo“ „details.path = {'16': foo}“ entspricht.

    • tabId

      Zahl

      Die ID des Tabs, für den Sie die Seitenaktion ändern möchten.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 oder höher

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

setPopup()

Promise 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Legt das HTML-Dokument fest, das als Pop-up geöffnet werden soll, wenn der Nutzer auf das Symbol der Seitenaktion klickt.

Parameter

  • Details

    Objekt

    • Pop-up

      String

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

    • tabId

      Zahl

      Die ID des Tabs, für den Sie die Seitenaktion ändern möchten.

  • callback

    function optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 oder höher

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

setTitle()

Promise 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Legt den Titel der Seitenaktion fest. Diese wird in einer Kurzinfo über der Seitenaktion angezeigt.

Parameter

  • Details

    Objekt

    • tabId

      Zahl

      Die ID des Tabs, für den Sie die Seitenaktion ändern möchten.

    • Titel

      String

      Der String für die Kurzinfo.

  • callback

    function optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 oder höher

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

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

Zeigt die Seitenaktion an. Die Seitenaktion wird immer angezeigt, wenn der Tab ausgewählt ist.

Parameter

  • tabId

    Zahl

    Die ID des Tabs, für den Sie die Seitenaktion ändern möchten.

  • callback

    function optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 oder höher

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

Ereignisse

onClicked

chrome.pageAction.onClicked.addListener(
  callback: function,
)

Wird ausgelöst, wenn auf ein Symbol für eine Seitenaktion geklickt wird. Dieses Ereignis wird nicht ausgelöst, wenn die Seitenaktion ein Pop-up hat.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (tab: tabs.Tab) => void