chrome.pageAction

Beschreibung

Verwende die chrome.pageAction API, um Symbole in der Google Chrome-Hauptsymbolleiste rechts neben der Adressleiste zu platzieren. Seitenaktionen stehen für 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

<ph type="x-smartling-placeholder"></ph> &amp;leq; 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 abonnieren können Feed für die aktuelle Seite.

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

Verwenden Sie stattdessen eine Browseraktion, damit Nutzer jederzeit mit Ihrem .

Manifest

Registrieren Sie die Seitenaktion wie folgt im Manifest der Erweiterung:

{
  "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- oder 1,2-fach immer häufiger verwendet werden, wird empfohlen, mehrere Größen für Ihre Symbole bereitzustellen. Chrome wählt die nächstgelegene aus und skaliert sie um den 16-Dip-Bereich zu füllen. So wird auch sichergestellt, dass Sie bei einer Änderung der Anzeigegröße noch etwas zu tun, um die verschiedenen Symbole bereitzustellen! Wenn der Größenunterschied jedoch zu extrem ist, kann diese Skalierung dazu führen, dass das Symbol Details verliert oder unscharf erscheint.

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

Bestandteile der Benutzeroberfläche

Wie Browseraktionen können auch Seitenaktionen ein Symbol, eine Kurzinfo und ein Pop-up-Fenster haben. keine Abzeichen haben, jedoch. Außerdem können Seitenaktionen ausgegraut sein. Sie finden Informationen zu Symbolen, Kurzinfos und Pop-ups finden Sie unter UI für Browseraktionen.

Mithilfe der Funktion pageAction.show und pageAction.hide-Methoden. Seitenaktionen werden standardmäßig ausgegraut dargestellt. Wenn Sie um es anzuzeigen, geben Sie den Tab an, auf 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:

  • Nutze 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. Browseraktionen verwenden .
  • Animieren Sie Ihr Symbol nicht ständig. Das ist einfach nervig.

Typen

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

getPopup()

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

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

Gibt Folgendes zurück:

  • Promise&lt;string&gt;

    Chrome 101 oder höher

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

Ruft den Titel der Seitenaktion ab.

Parameter

  • Details

    TabDetails

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (result: string) => void

    • Ergebnis

      String

Gibt Folgendes zurück:

  • Promise&lt;string&gt;

    Chrome 101 oder höher

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

hide()

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

Blendet die Seitenaktion aus. Ausgeblendete Seitenaktionen werden weiterhin in der Chrome-Symbolleiste angezeigt, sind jedoch 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

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 101 oder höher

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

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

Parameter

  • Details

    Objekt

    • iconIndex

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

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 101 oder 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.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.

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

      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

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 101 oder höher

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

Legt den Titel der Seitenaktion fest. 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 der Kurzinfo.

  • callback

    Funktion optional

    Chrome 67 und höher

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 101 oder höher

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

show()

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

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

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 101 oder höher

    Promise-Objekte 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 Aktionssymbol für die Seite geklickt wird Dieses Ereignis wird nicht ausgelöst, wenn die Seitenaktion ein Pop-up enthält.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (tab: tabs.Tab) => void