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 und höher MV3+

Konzepte und Verwendung

Mit der Side Panel API können Erweiterungen ihre eigene Benutzeroberfläche in der Seitenleiste anzeigen. Dadurch ist eine dauerhafte Nutzung möglich, die das Surfen der Nutzer ergänzt.

<ph type="x-smartling-placeholder">
</ph> Drop-down-Menü der Seitenleiste <ph type="x-smartling-placeholder">
</ph> Benutzeroberfläche der Seitenleiste des Chrome-Browsers

Zu den Funktionen gehören:

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

Anwendungsfälle

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

Dieselbe Seitenleiste auf jeder Website anzeigen

Die Seitenleiste kann anfänglich ü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 mit sidepanel.setOptions() eine Seitenleiste auf einem bestimmten Tab aktivieren. In diesem Beispiel wird chrome.tabs.onUpdated() verwendet, um auf Aktualisierungen auf dem Tab zu warten. Dabei wird geprüft, ob die URL www.google.com lautet, und die Seitenleiste wird aktiviert. Andernfalls wird es 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, für die die Seitenleiste nicht aktiviert ist, wird die Seitenleiste geschlossen und die Erweiterung nicht im Drop-down-Menü der Seitenleiste angezeigt.

Ein vollständiges Beispiel finden Sie unter Beispiel für eine tabellarische Seitenleiste.

Öffnen Sie die Seitenleiste, indem Sie auf das Symbol in der Symbolleiste klicken

Entwickler können Nutzern erlauben, die Seitenleiste zu öffnen, wenn sie auf das Symbol für die Aktionssymbole sidePanel.setPanelBehavior() klicken. Deklariere 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 diesen Code in das vorherige Beispiel ein:

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 einer Nutzerinteraktion programmatisch öffnen

Mit Chrome 116 wird sidePanel.open() eingeführt. Erweiterungen können die Seitenleiste durch eine Nutzergeste für eine Erweiterung öffnen, z. B. durch Klicken auf das Aktionssymbol. Eine Nutzerinteraktion auf einer Erweiterungsseite oder ein Content-Skript, z. B. ein Klick 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 Datei geöffnet werden soll. Verwende windowId, um eine globale Seitenleiste zu öffnen. Alternativ können Sie tabId so einstellen, dass die Seitenleiste nur auf 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 die aktuelle Seitenleiste über sidepanel.getOptions() abrufen. Im folgenden Beispiel wird eine Seitenleiste mit der Begrüßung für runtime.onInstalled() festgelegt. Wenn der Nutzer dann zu einem anderen Tab wechselt, wird dieser durch die Hauptseite 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.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});

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

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

Nutzerfreundlichkeit der Seitenleiste

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

Seitenleiste öffnen

Damit Nutzer die Seitenleiste öffnen können, musst du ein Aktionssymbol in Kombination verwenden mit sidePanel.setPanelBehavior(). Alternativ können Sie nach einer Nutzerinteraktion sidePanel.open() aufrufen, z. B.:

Seitenleiste anpinnen

<ph type="x-smartling-placeholder">
</ph> Symbol „Anpinnen“ auf der Benutzeroberfläche der Seitenleiste. <ph type="x-smartling-placeholder">
</ph> Symbol „Anpinnen“ auf der Benutzeroberfläche der Seitenleiste.

Wenn die Seitenleiste geöffnet ist, wird in der Symbolleiste der Seitenleiste ein Stecknadelsymbol angezeigt. Wenn Sie darauf klicken, wird das Aktionssymbol Ihrer Erweiterung angepinnt. Durch Klicken auf das Aktionssymbol Durch das Anheften wird die Standardaktion für das Aktionssymbol ausgeführt. Seitenleiste öffnen, wenn dies explizit konfiguriert wurde.

Beispiele

Weitere Demos für die Side Panel API-Erweiterungen finden Sie in den folgenden Erweiterungen:

Typen

GetPanelOptions

Attribute

  • tabId

    Zahl optional

    Wenn angegeben, werden die Optionen der Seitenleiste für den jeweiligen Tab zurückgegeben. Andernfalls werden die standardmäßigen Optionen der Seitenleiste verwendet. Diese werden für alle Tabs ohne bestimmte Einstellungen verwendet.

OpenOptions

Chrome 116 und höher

Attribute

  • tabId

    Zahl optional

    Der Tab, in dem die Seitenleiste geöffnet werden soll. Wenn der entsprechende Tab eine tabellarische Seitenleiste hat, wird sie nur für diesen Tab geöffnet. Wenn kein tabellarisches Steuerfeld vorhanden ist, wird das globale Steuerfeld in dem angegebenen Tab und allen anderen Tabs geöffnet, die derzeit keinen tabellarischen Bereich haben. Dadurch werden alle derzeit aktiven Seitenleisten (global oder tabulatorspezifisch) auf dem entsprechenden Tab überschrieben. Es muss mindestens eines dieser Werte oder windowId angegeben werden.

  • windowId

    Zahl optional

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

PanelBehavior

Attribute

  • openPanelOnActionClick

    Boolescher Wert optional

    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 im Erweiterungspaket sein.

  • tabId

    Zahl optional

    Wenn angegeben, gelten die Optionen in der Seitenleiste nur für den Tab mit dieser ID. Wenn keine Angabe gemacht wird, legen diese Optionen das Standardverhalten fest. Diese Option wird für alle Tabs verwendet, die keine spezifischen Einstellungen haben. Hinweis: Wenn für diese tabId und die standardmäßige tabId derselbe Pfad festgelegt ist, ist das Steuerfeld für diese tabId eine andere Instanz als das Steuerfeld für die standardmäßige tabId.

SidePanel

Attribute

  • default_path

    String

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

Methoden

getOptions()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Gibt die Konfiguration des aktiven Steuerfelds zurück.

Parameter

  • Optionen

    GetPanelOptions

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (options: PanelOptions) => void

Gibt Folgendes zurück:

  • Promise&lt;PanelOptions&gt;

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

getPanelBehavior()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (behavior: PanelBehavior) => void

Gibt Folgendes zurück:

  • Promise&lt;PanelBehavior&gt;

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

open()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 116 und höher 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Ö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.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

setOptions()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Konfiguriert die Seitenleiste.

Parameter

  • Optionen

    PanelOptions

    Die Konfigurationsoptionen, die auf das Steuerfeld angewendet werden sollen.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.

setPanelBehavior()

<ph type="x-smartling-placeholder"></ph> Versprechen 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

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

Parameter

  • zum weltweiten Kundenverhalten.

    PanelBehavior

    Das neue Verhalten, das festgelegt werden soll.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks sind jedoch für Abwärtskompatibilität. Sie können nicht beide in demselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.