chrome.sidePanel

Beschreibung

Mit der chrome.sidePanel API kannst du Inhalte in der Seitenleiste des Browsers neben dem Hauptinhalt einer Webseite hosten.

Berechtigungen

sidePanel

Wenn Sie die Side Panel API verwenden möchten, fügen Sie der Manifestdatei der Erweiterung die Berechtigung "sidePanel" hinzu:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "permissions": [
    "sidePanel"
  ]
}

Verfügbarkeit

Chrome 114+ MV3+

Konzepte und Nutzung

Mit der Side Panel API können Erweiterungen ihre eigene UI in der Seitenleiste anzeigen lassen, um eine dauerhafte Nutzung zu ermöglichen, die den Browserverlauf des Nutzers ergänzt.

Drop-down-Menü der Seitenleiste
Benutzeroberfläche der Seitenleiste des Chrome-Browsers.

Zu den Funktionen gehören:

  • Die Seitenleiste bleibt beim Wechseln zwischen Tabs geöffnet, sofern sie konfiguriert ist.
  • Sie kann nur auf bestimmten Websites verfügbar sein.
  • Als Erweiterungsseite haben die Seitenleisten Zugriff auf alle Chrome APIs.
  • In den Chrome-Einstellungen können Nutzer angeben, auf welcher Seite der Bereich angezeigt werden soll.

Anwendungsfälle

In den folgenden Abschnitten werden einige häufige Anwendungsfälle für die Seitenleisten-API beschrieben. Vollständige Beispiele für Erweiterungen finden Sie unter Beispiele für Erweiterungen.

Auf jeder Website dieselbe Seitenleiste anzeigen

Die Seitenleiste kann anfangs über die Eigenschaft "default_path" im Schlüssel "side_panel" des Manifests festgelegt werden, um dieselbe Seitenleiste auf jeder Website anzuzeigen. Dieser sollte auf einen relativen Pfad innerhalb des Erweiterungsverzeichnisses verweisen.

manifest.json:

{
  "name": "My side panel extension",
  ...
  "side_panel": {
    "default_path": "sidepanel.html"
  }
  ...
}

sidepanel.html:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidepanel</title>
  </head>
  <body>
    <h1>All sites sidepanel extension</h1>
    <p>This side panel is enabled on all sites</p>
  </body>
</html>

Seitenleiste auf einer bestimmten Website aktivieren

Eine Erweiterung kann sidepanel.setOptions() verwenden, um eine Seitenleiste auf einem bestimmten Tab zu aktivieren. In diesem Beispiel wird chrome.tabs.onUpdated() verwendet, um auf Aktualisierungen des Tabs zu warten. Es prüft, ob die URL www.google.com lautet, und aktiviert die Seitenleiste. Andernfalls wird sie deaktiviert.

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the side panel on google.com
  if (url.origin === GOOGLE_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Wenn ein Nutzer vorübergehend zu einem Tab wechselt, auf dem die Seitenleiste nicht aktiviert ist, wird die Seitenleiste ausgeblendet. Sie wird automatisch wieder angezeigt, wenn der Nutzer zu einem Tab wechselt, in dem er zuvor geöffnet war.

Wenn der Nutzer eine Website aufruft, auf der die Seitenleiste nicht aktiviert ist, wird die Seitenleiste geschlossen und die Erweiterung wird nicht im Drop-down-Menü der Seitenleiste angezeigt.

Ein vollständiges Beispiel finden Sie in der tabspezifischen Seitenleiste.

Seitenleiste öffnen, indem du auf das Symbol in der Symbolleiste klickst

Entwickler können Nutzern erlauben, die Seitenleiste zu öffnen, wenn sie auf das Symbol der Aktionssymbolleiste mit sidePanel.setPanelBehavior() klicken. Deklarieren Sie zuerst im Manifest den Schlüssel "action":

manifest.json:

{
  "name": "My side panel extension",
  ...
   "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Fügen Sie nun diesen Code zum vorherigen Beispiel hinzu:

service-worker.js:

const GOOGLE_ORIGIN = 'https://www.google.com';

// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Seitenleiste bei Nutzerinteraktion programmatisch öffnen

Mit Chrome 116 wird sidePanel.open() eingeführt. Erweiterungen können die Seitenleiste über eine Nutzergeste öffnen, z. B. durch Klicken auf das Aktionssymbol. Oder eine Nutzerinteraktion auf einer Erweiterungsseite oder einem Inhaltsskript, z. B. Klicken auf eine Schaltfläche. Eine vollständige Demo finden Sie in der Beispielerweiterung Seitenleiste öffnen.

Der folgende Code zeigt, wie eine globale Seitenleiste im aktuellen Fenster geöffnet wird, wenn der Nutzer auf ein Kontextmenü klickt. Wenn Sie sidePanel.open() verwenden, müssen Sie den Kontext auswählen, in dem die App geöffnet werden soll. Verwenden Sie windowId, um eine globale Seitenleiste zu öffnen. Alternativ können Sie das Symbol tabId so konfigurieren, dass die Seitenleiste nur in einem bestimmten Tab geöffnet wird.

service-worker.js:

chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open side panel',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

Zu einem anderen Bereich wechseln

Erweiterungen können sidepanel.getOptions() verwenden, um die aktuelle Seitenleiste abzurufen. Im folgenden Beispiel wird eine Begrüßungsseite für runtime.onInstalled() festgelegt. Wenn die Nutzenden dann zu einem anderen Tab wechseln, wird dieser durch die Hauptseitenleiste ersetzt.

service-worker.js:

const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';

chrome.runtime.onInstalled.addListener(() => {
  chrome.sidePanel.setOptions({ path: welcomePage });
});

chrome.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Ein vollständiges Beispiel finden Sie unter Mehrere Seitenleisten.

Nutzerfreundlichkeit der Seitenleiste

Nutzer sehen zuerst die integrierten Seitenleisten von Chrome. In jeder Seitenleiste wird das Symbol der Erweiterung im Seitenleistenmenü angezeigt. Wenn keine Symbole eingefügt werden, wird ein Platzhaltersymbol mit dem ersten Buchstaben des Namens der Erweiterung angezeigt.

Seitenleiste öffnen

Zum Menü in der Seitenleiste navigieren
Die verfügbaren Seitenleisten finden Nutzer im Seitenleistenmenü. Anschließend kann er eine Erweiterung aus dem Drop-down-Menü auswählen.
Drop-down-Menü der Seitenleiste
Benutzeroberfläche der Seitenleiste des Chrome-Browsers.
Durch eine Nutzergeste öffnen

Sie können die Seitenleiste über Nutzerinteraktionen mit sidePanel.open() und sidePanel.setPanelBehavior() öffnen, z. B.:

Beispiele

Weitere Demos zu Side Panel API-Erweiterungen finden Sie in den folgenden Erweiterungen:

Typen

GetPanelOptions

Attribute

  • tabId

    Nummer optional

    Wenn angegeben, werden die Seitenleistenoptionen für den angegebenen Tab zurückgegeben. Andernfalls werden die Standardoptionen der Seitenleiste zurückgegeben, die für alle Tabs verwendet werden, die keine bestimmten Einstellungen haben.

OpenOptions

Chrome 116 oder höher

Attribute

  • tabId

    Nummer optional

    Der Tab, in dem die Seitenleiste geöffnet werden soll. Wenn der entsprechende Tab eine tabulatorspezifische Seitenleiste hat, wird diese nur für diesen Tab geöffnet. Wenn kein tabulatorspezifisches Steuerfeld vorhanden ist, wird das globale Steuerfeld auf dem angegebenen Tab und auf allen anderen Tabs geöffnet, für die kein Tab mit einem aktuell geöffneten Steuerfeld vorhanden ist. Dadurch werden alle derzeit aktiven Seitenleisten (global oder tabulatorspezifisch) im entsprechenden Tab überschrieben. Es muss mindestens eine dieser Optionen oder windowId angegeben werden.

  • windowId

    Nummer optional

    Das Fenster, in dem die Seitenleiste geöffnet werden soll. Dies gilt nur, wenn die Erweiterung eine globale (nicht tabulatorspezifische) Seitenleiste hat oder wenn tabId ebenfalls angegeben ist. Dadurch werden alle derzeit aktiven globalen Seitenleisten überschrieben, die der Nutzer im jeweiligen Fenster geöffnet hat. Es muss mindestens eine dieser Optionen oder tabId angegeben werden.

PanelBehavior

Attribute

  • openPanelOnActionClick

    Boolescher Wert optional

    Gibt an, ob beim Klicken auf das Symbol der Erweiterung der Eintrag der Erweiterung in der Seitenleiste angezeigt wird. Die Standardeinstellung ist "false".

PanelOptions

Attribute

  • aktiviert

    Boolescher Wert optional

    Legt fest, ob die Seitenleiste aktiviert werden soll. Dies ist optional. Der Standardwert ist true.

  • Pfad

    String optional

    Der Pfad zur HTML-Datei der Seitenleiste, die verwendet werden soll. Dies muss eine lokale Ressource innerhalb des Erweiterungspakets sein.

  • tabId

    Nummer optional

    Wenn angegeben, gelten die Optionen in der Seitenleiste nur für den Tab mit dieser ID. Wenn diese Optionen weggelassen werden, wird das Standardverhalten festgelegt, das für alle Tabs verwendet wird, die keine bestimmten Einstellungen haben. Hinweis: Wenn für diese tabId und die standardmäßige tabId der gleiche Pfad festgelegt ist, ist das Steuerfeld für diese tabId eine andere Instanz als das Feld für die standardmäßige tabId (tabId).

SidePanel

Attribute

  • default_path

    String

    Vom Entwickler angegebener Pfad für die Seitenleistenanzeige.

Methoden

getOptions()

Versprechen 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Gibt die Konfiguration des aktiven Bereichs zurück.

Parameters

  • Optionen

    GetPanelOptions

    Gibt den Kontext an, für den die Konfiguration zurückgegeben werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (options: PanelOptions)=>void

Rückgaben

  • Promise<PanelOptions>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

getPanelBehavior()

Versprechen 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

Gibt das aktuelle Verhalten der Seitenleiste der Erweiterung zurück.

Parameters

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (behavior: PanelBehavior)=>void

Rückgaben

  • Promise<PanelBehavior>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

open()

Versprechen Chrome 116 oder höher 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Öffnet die Seitenleiste für die Erweiterung. Dieser Parameter kann nur als Reaktion auf eine Nutzeraktion aufgerufen werden.

Parameters

  • Optionen

    OpenOptions

    Gibt den Kontext an, in dem die Seitenleiste geöffnet werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

setOptions()

Versprechen 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Konfiguriert die Seitenleiste.

Parameters

  • Optionen

    PanelOptions

    Die Konfigurationsoptionen, die auf den Bereich angewendet werden sollen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

setPanelBehavior()

Versprechen 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Konfiguriert das Verhalten der Seitenleiste der Erweiterung. Dies ist ein Upsert-Vorgang.

Parameters

  • zum weltweiten Kundenverhalten.

    PanelBehavior

    Das festzulegende neue Verhalten.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.