browser.sidePanel

Beschreibung

Mit der chrome.sidePanel API können Sie 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 die Berechtigung "sidePanel" in der Manifestdatei der Erweiterung hinzu:

manifest.json:

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

Verfügbarkeit

Chrome 114+ browser.* seit Chrome 148 MV3+

Konzepte und Verwendung

Mit der Side Panel API können Erweiterungen ihre eigene Benutzeroberfläche in der Seitenleiste anzeigen. So können sie dauerhafte Funktionen bereitstellen, die das Surfen im Web ergänzen.

Drop-down-Menü in der Seitenleiste
Benutzeroberfläche der Seitenleiste im Chrome-Browser.

Zu den Funktionen gehören:

  • Die Seitenleiste bleibt beim Wechseln zwischen Tabs geöffnet, wenn dies so eingestellt ist.
  • Sie ist möglicherweise nur auf bestimmten Websites verfügbar.
  • Als Erweiterungsseite haben Seitenleisten Zugriff auf alle Chrome APIs.
  • In den Chrome-Einstellungen können Nutzer festlegen, auf welcher Seite die Seitenleiste angezeigt werden soll.

Anwendungsfälle

In den folgenden Abschnitten werden einige gängige Anwendungsfälle für die Side Panel API beschrieben. Vollständige Beispiele für Erweiterungen finden Sie unter Beispiele für Erweiterungen.

Auf jeder Website dieselbe Seitenleiste anzeigen

Die Seitenleiste kann anfänglich über die Property "default_path" im Schlüssel "side_panel" des Manifests festgelegt werden, damit auf jeder Website dieselbe Seitenleiste angezeigt wird. Dieser sollte auf einen relativen Pfad im Erweiterungsverzeichnis 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 browser.tabs.onUpdated() verwendet, um auf Aktualisierungen des Tabs zu warten. Sie 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';

browser.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 browser.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the side panel on all other sites
    await browser.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Wenn ein Nutzer vorübergehend zu einem Tab wechselt, in dem die Seitenleiste nicht aktiviert ist, wird sie ausgeblendet. Sie wird automatisch wieder angezeigt, wenn der Nutzer zu einem Tab wechselt, in dem sie 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 im Beispiel Tabspezifische Seitenleiste.

Seitenleiste durch Klicken auf das Symbol in der Symbolleiste öffnen

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

manifest.json:

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

Fügen Sie nun den folgenden 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
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Seitenleiste bei Nutzerinteraktion programmatisch öffnen

Mit Chrome 116 wird sidePanel.open() eingeführt. Damit können Erweiterungen die Seitenleiste über eine Nutzergeste der Erweiterung öffnen, z. B. durch Klicken auf das Aktionssymbol. Oder eine Nutzerinteraktion auf einer Erweiterungsseite oder in einem Inhaltsskript, z. B. das 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 es geöffnet werden soll. Mit windowId können Sie eine globale Seitenleiste öffnen. Alternativ können Sie tabId festlegen, damit die Seitenleiste nur auf einem bestimmten Tab geöffnet wird.

service-worker.js:

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

browser.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // This will open the panel in all the pages on the current window.
    browser.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 Willkommens-Seitenleiste für runtime.onInstalled() festgelegt. Wenn der Nutzer dann zu einem anderen Tab wechselt, wird die Seitenleiste durch die Hauptseitenleiste ersetzt.

service-worker.js:

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

browser.runtime.onInstalled.addListener(() => {
  browser.sidePanel.setOptions({ path: welcomePage });
  browser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

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

Den vollständigen Code finden Sie im Beispiel Mehrere Seitenleisten.

Seitenleiste

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

Seitenleiste öffnen

Wenn Sie Nutzern das Öffnen der Seitenleiste ermöglichen möchten, verwenden Sie ein Aktionssymbol in Kombination mit sidePanel.setPanelBehavior(). Alternativ können Sie sidePanel.open() nach einer Nutzerinteraktion aufrufen, z. B.:

Seitenleiste anpinnen

Symbol „Anpinnen“ in der Seitenleiste
Anpinn-Symbol in der Seitenleiste.

In der Symbolleiste der Seitenleiste wird ein Stecknadelsymbol angezeigt, wenn die Seitenleiste geöffnet ist. Wenn Sie auf das Symbol klicken, wird das Aktionssymbol Ihrer Erweiterung angepinnt. Wenn Sie auf das Aktionssymbol klicken, nachdem es angepinnt wurde, wird die Standardaktion für das Aktionssymbol ausgeführt. Die Seitenleiste wird nur geöffnet, wenn dies explizit konfiguriert wurde.

Beispiele

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

Typen

CloseOptions

Chrome 141+ browser.* seit Chrome 148

Attribute

  • tabId

    number optional

    Der Tab, in dem die Seitenleiste geschlossen werden soll. Wenn im angegebenen Tab eine tabspezifische Seitenleiste geöffnet ist, wird sie für diesen Tab geschlossen. Wenn nur die globale Seitenleiste geöffnet ist, wird das Promise, das vom Aufruf von close() zurückgegeben wird, mit einem Fehler abgelehnt. Dieses Verhalten wurde in Chrome 145 geändert. In früheren Versionen wurde stattdessen das globale Steuerfeld geschlossen. Es muss entweder dieses Feld oder windowId angegeben werden.

  • windowId

    number optional

    Das Fenster, in dem die Seitenleiste geschlossen werden soll. Wenn im angegebenen Fenster eine globale Seitenleiste geöffnet ist, wird sie für alle Tabs in diesem Fenster geschlossen, in denen keine tabspezifische Seitenleiste aktiv ist. Es muss entweder dieses Feld oder tabId angegeben werden.

GetPanelOptions

Attribute

  • tabId

    number optional

    Falls angegeben, werden die Seitenleistenoptionen für den angegebenen Tab zurückgegeben. Andernfalls werden die Standardoptionen für die Seitenleiste zurückgegeben, die für alle Tabs ohne spezifische Einstellungen verwendet werden.

OpenOptions

Chrome 116 und höher browser.* seit Chrome 148

Attribute

  • tabId

    number optional

    Der Tab, in dem die Seitenleiste geöffnet werden soll. Wenn der entsprechende Tab eine tabspezifische Seitenleiste hat, wird die Seitenleiste nur für diesen Tab geöffnet. Wenn es keinen tabspezifischen Bereich gibt, wird der globale Bereich im angegebenen Tab und in allen anderen Tabs ohne aktuell geöffneten tabspezifischen Bereich geöffnet. Dadurch wird jede derzeit aktive Seitenleiste (global oder tabspezifisch) im entsprechenden Tab überschrieben. Es muss entweder dieses Feld oder windowId angegeben werden.

  • windowId

    number optional

    Das Fenster, in dem die Seitenleiste geöffnet werden soll. Dies gilt nur, wenn die Erweiterung eine globale (nicht tabspezifische) Seitenleiste hat oder tabId ebenfalls angegeben ist. Dadurch wird jede derzeit aktive globale Seitenleiste überschrieben, die der Nutzer im angegebenen Fenster geöffnet hat. Es muss entweder dieses Feld oder tabId angegeben werden.

PanelBehavior

Attribute

  • openPanelOnActionClick

    Boolesch optional

    Gibt an, ob durch Klicken auf das Symbol der Erweiterung der Eintrag der Erweiterung in der Seitenleiste ein- oder ausgeblendet wird. Die Standardeinstellung ist "false".

PanelClosedInfo

Chrome 142+ browser.* seit Chrome 148

Attribute

  • Pfad

    String

    Der Pfad der lokalen Ressource im Erweiterungspaket, deren Inhalt im Steuerfeld angezeigt wird.

  • tabId

    number optional

    Die optionale ID des Tabs, auf dem die Seitenleiste geschlossen wurde. Dies wird nur angegeben, wenn das Steuerfeld tabspezifisch ist.

  • windowId

    Zahl

    Die ID des Fensters, in dem die Seitenleiste geschlossen wurde. Diese Option ist sowohl für globale als auch für tabspezifische Bereiche verfügbar.

PanelLayout

Chrome 140+ browser.* seit Chrome 148

Attribute

PanelOpenedInfo

Chrome 141+ browser.* seit Chrome 148

Attribute

  • Pfad

    String

    Der Pfad der lokalen Ressource im Erweiterungspaket, deren Inhalt im Steuerfeld angezeigt wird.

  • tabId

    number optional

    Die optionale ID des Tabs, auf dem die Seitenleiste geöffnet wird. Dies wird nur angegeben, wenn das Steuerfeld tabspezifisch ist.

  • windowId

    Zahl

    Die ID des Fensters, in dem die Seitenleiste geöffnet ist. Diese Option ist sowohl für globale als auch für tabspezifische Bereiche verfügbar.

PanelOptions

Attribute

  • aktiviert

    Boolesch optional

    Gibt an, ob die Seitenleiste aktiviert werden soll. Dies ist optional. Der Standardwert ist true.

  • Pfad

    String optional

    Der Pfad zur HTML-Datei für die Seitenleiste, die verwendet werden soll. Dies muss eine lokale Ressource im Erweiterungspaket sein.

  • tabId

    number optional

    Wenn angegeben, gelten die Optionen für die Seitenleiste nur für den Tab mit dieser ID. Wenn diese Optionen weggelassen werden, wird das Standardverhalten festgelegt (für alle Tabs ohne spezifische Einstellungen verwendet). Hinweis: Wenn für diese „tabId“ und die Standard-„tabId“ derselbe Pfad festgelegt ist, ist das Steuerfeld für diese „tabId“ eine andere Instanz als das Steuerfeld für die Standard-„tabId“.

Side

Chrome 140+ browser.* seit Chrome 148

Definiert die mögliche Ausrichtung der Seitenleiste in der Browser-UI.

Enum

"left"

"right"

SidePanel

Attribute

  • default_path

    String

    Vom Entwickler angegebener Pfad für die Anzeige in der Seitenleiste.

Methoden

close()

Chrome 141+ browser.* seit Chrome 148 
browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

Schließt die Seitenleiste der Erweiterung. Dies ist ein No-Op, wenn das Steuerfeld bereits geschlossen ist.

Parameter

  • Optionen

    CloseOptions

    Gibt den Kontext an, in dem die Seitenleiste geschlossen werden soll.

Ausgabe

  • Promise<void>

    Gibt ein Promise zurück, das aufgelöst wird, wenn die Seitenleiste geschlossen wurde.

getLayout()

Chrome 140+ browser.* seit Chrome 148 
browser.sidePanel.getLayout(): Promise<PanelLayout>

Gibt das aktuelle Layout der Seitenleiste zurück.

Ausgabe

getOptions()

browser.sidePanel.getOptions(
  options: GetPanelOptions,
): Promise<PanelOptions>

Gibt die aktive Bereichskonfiguration zurück.

Parameter

  • Optionen

    GetPanelOptions

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

Ausgabe

  • Promise<PanelOptions>

    Gibt ein Promise zurück, das mit der aktiven Steuerfeldkonfiguration aufgelöst wird.

getPanelBehavior()

browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>

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

Ausgabe

  • Promise<PanelBehavior>

    Gibt ein Promise zurück, das mit dem Verhalten der Seitenleiste der Erweiterung aufgelöst wird.

open()

Chrome 116 und höher browser.* seit Chrome 148 
browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

Öffnet die Seitenleiste für die Erweiterung. Dies darf nur als Reaktion auf eine Nutzeraktion aufgerufen werden.

Parameter

  • Optionen

    OpenOptions

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

Ausgabe

  • Promise<void>

    Gibt ein Promise zurück, das aufgelöst wird, wenn die Seitenleiste geöffnet wurde.

setOptions()

browser.sidePanel.setOptions(
  options: PanelOptions,
): Promise<void>

Konfiguriert die Seitenleiste.

Parameter

  • Optionen

    PanelOptions

    Die Konfigurationsoptionen, die auf das Steuerfeld angewendet werden sollen.

Ausgabe

  • Promise<void>

    Gibt ein Promise zurück, das aufgelöst wird, wenn die Optionen festgelegt wurden.

setPanelBehavior()

browser.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
): Promise<void>

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

Parameter

  • zum weltweiten Kundenverhalten.

    PanelBehavior

    Das neue Verhalten, das festgelegt werden soll.

Ausgabe

  • Promise<void>

    Gibt ein Promise zurück, das aufgelöst wird, wenn das neue Verhalten festgelegt wurde.

Ereignisse

onClosed

Chrome 142+ browser.* seit Chrome 148 
browser.sidePanel.onClosed.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Seitenleiste der Erweiterung geschlossen wird.

Parameter

onOpened

Chrome 141+ browser.* seit Chrome 148 
browser.sidePanel.onOpened.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Seitenleiste der Erweiterung geöffnet wird.

Parameter