chrome.pageAction

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 für alle Seiten gelten. Seitenaktionen werden ausgegraut angezeigt, 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 steht für eine Seitenaktion, mit der Sie den RSS-Feed für die aktuelle Seite abonnieren können.

Ausgeblendete Seitenaktionen werden ausgegraut dargestellt. Der RSS-Feed unten ist beispielsweise ausgegraut, da Sie den Feed für die aktuelle Seite nicht abonnieren können:

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

Manifest

Registrieren Sie Ihre Seitenaktion im Erweiterungsmanifest 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 nächstgelegene aus und skaliert es, um den Bereich mit 16 Dips auszufüllen. So müssen Sie auch keine weiteren Symbole bereitstellen, wenn sich die Anzeigegröße des Symbols ändert. Wenn der Größenunterschied jedoch zu groß ist, kann es durch die Skalierung zu Detailverlusten oder Unschärfe kommen.

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 Seitenaktionen ein Symbol, eine Kurzinfo und ein Pop-up-Fenster haben. Sie können jedoch keine Badges haben. Außerdem können Seitenaktionen ausgegraut sein. Informationen zu Symbolen, Kurzinfos und Pop-ups finden Sie im Abschnitt 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 dargestellt. Wenn Sie es anzeigen, geben Sie den Tab an, auf dem das Symbol erscheinen 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 bestmögliche visuelle Wirkung zu erzielen:

  • Verwenden Sie Seitenaktionen für Funktionen, die nur für wenige Seiten sinnvoll sind.
  • Verwenden Sie Seitenaktionen nicht 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 und höher

Attribute

  • tabId

    number optional

    Die ID des Tabs, für den der 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

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string) => void

    • Ergebnis

      String

Ausgabe

  • Promise<string>

    Chrome 101 und 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

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string) => void

    • Ergebnis

      String

Ausgabe

  • Promise<string>

    Chrome 101 und 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

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 und 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, als Pixeldaten eines Canvas-Elements oder als Dictionary mit einem der beiden angegeben werden. Entweder die Eigenschaft path oder die Eigenschaft imageData muss angegeben werden.

Parameter

  • Details

    Objekt

    • iconIndex

      number optional

      Veraltet. Dieses Argument wird ignoriert.

    • imageData

      ImageData | object optional

      Entweder ein ImageData-Objekt oder ein Dictionary {size -> ImageData}, das das festzulegende Symbol darstellt. Wenn das Symbol als Dictionary angegeben wird, wird das tatsächlich zu verwendende Bild in Abhängigkeit von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Einheit des Bildschirmbereichs passen, gleich 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. Hinweis: „details.imageData = foo“ entspricht „details.imageData = {'16': foo}“.

    • Pfad

      String | Objekt optional

      Entweder ein relativer Bildpfad oder ein Dictionary {size -> relativer Bildpfad}, das auf das festzulegende Symbol verweist. Wenn das Symbol als Dictionary angegeben wird, wird das tatsächlich zu verwendende Bild in Abhängigkeit von der Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Einheit des Bildschirmbereichs passen, gleich 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“ mit „details.path = {'16': foo}“ identisch ist.

    • tabId

      Zahl

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 und 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 den 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

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 und 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. Sie 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 Kurzinfo-String.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 und 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

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 101 und 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