chrome.pageAction

Beschreibung

Verwenden Sie die chrome.pageAction API, um Symbole in der Hauptsymbolleiste von Google Chrome rechts neben der Adressleiste zu platzieren. Seitenaktionen sind Aktionen, die auf der aktuellen Seite ausgeführt werden können, aber nicht für alle Seiten gelten. Seitenaktionen werden bei Inaktivität ausgegraut.

Verfügbarkeit

≤ MV2

Beispiele:

  • RSS-Feed dieser Seite abonnieren
  • Diashow aus den Fotos 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 folgende RSS-Feed ist beispielsweise ausgegraut, da du den Feed für die aktuelle Seite nicht abonnieren kannst:

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

Manifest

Registrieren Sie die 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,5x oder 1,2x immer häufiger verwendet werden, sollten Sie mehrere Größen für Symbole bereitstellen. Chrome wählt die am nächsten gelegene aus und skaliert sie so, dass sie den 16-Dip-Bereich füllt. So ist auch sichergestellt, dass Sie keine weiteren Symbole erstellen müssen, falls sich die Größe der Anzeige ändern sollte. Wenn der Größenunterschied jedoch zu extrem ist, kann diese Skalierung dazu führen, dass das Symbol an Details verloren geht oder unscharf wirkt.

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. Sie können jedoch keine Badges haben. Außerdem können Seitenaktionen ausgegraut sein. Informationen zu Symbolen, Kurzinfos und Pop-ups finden Sie unter UI für Browseraktionen.

Mit der Methode pageAction.show bzw. pageAction.hide können Sie eine Seitenaktion ein- und ausblenden. Standardmäßig werden Seitenaktionen ausgegraut. Dabei 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 eine optimale visuelle Wirkung zu erzielen:

  • Verwende Seitenaktionen nur 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 das Symbol nicht ständig. Das ist nur ärgerlich.

Typen

ImageDataType

Pixel-Daten 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

    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

getPopup()

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

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

Parameters

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string)=>void

    • Ergebnis

      String

Rückgaben

  • Versprechen<string>

    Chrome 101 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.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Ruft den Titel der Seitenaktion ab.

Parameters

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string)=>void

    • Ergebnis

      String

Rückgaben

  • Versprechen<string>

    Chrome 101 und höher

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

hide()

Versprechen 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

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

Parameters

  • tabId

    Zahl

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

  • callback

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 101 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.pageAction.setIcon(
  details: object,
  callback?: function,
)

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

Parameters

  • Details

    Objekt

    • iconIndex

      Nummer 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 tatsächlich zu verwendende 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 das festzulegende Symbol verweist. Wenn das Symbol als Wörterbuch angegeben ist, wird das tatsächlich zu verwendende 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

      Zahl

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 101 und höher

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

setPopup()

Versprechen 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
)

Legt fest, dass das HTML-Dokument als Pop-up geöffnet wird, wenn der Nutzer auf das Symbol der Seitenaktion 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

      Zahl

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

  • callback

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 101 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.pageAction.setTitle(
  details: object,
  callback?: function,
)

Legt den Titel der Seitenaktion fest. Dies wird in einer Kurzinfo zur Seitenaktion angezeigt.

Parameters

  • 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

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 101 und höher

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

show()

Versprechen 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

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

Parameters

  • tabId

    Zahl

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

  • callback

    Funktion optional

    Chrome 67 oder höher

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

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

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (tab: tabs.Tab)=>void