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
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.
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.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 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
Damit Nutzer die Seitenleiste öffnen können, verwende ein Aktionssymbol in Kombination mit sidePanel.setPanelBehavior()
. Alternativ können Sie sidePanel.open()
nach einer Nutzerinteraktion aufrufen, z. B.:
- Einen Aktionsklick
- Eine Tastenkombination
- Ein Kontextmenü
- Eine Nutzergeste auf einer Erweiterungsseite oder einem Inhaltsskript.
Seitenleiste anpinnen
In der Symbolleiste der Seitenleiste wird ein Stecknadelsymbol angezeigt, wenn die Seitenleiste geöffnet ist. Wenn Sie auf das Symbol klicken, wird das Aktionssymbol der Erweiterung angepinnt. Wenn Sie nach dem Anpinnen auf das Aktionssymbol klicken, 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:
- Seitenleiste für Wörterbuch:
- Globale Seitenleiste:
- Mehrere Seitenleisten:
- Seitenleiste öffnen
- Websitespezifische Seitenleiste:
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
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 odertabId
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()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Gibt die Konfiguration des aktiven Bereichs zurück.
Parameter
-
Optionen
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
-
Optionen
-
Returns
-
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()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Gibt das aktuelle Verhalten der Seitenleiste der Erweiterung zurück.
Parameter
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(behavior: PanelBehavior) => void
-
zum weltweiten Kundenverhalten.
-
Returns
-
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()
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.
Parameter
-
Optionen
Gibt den Kontext an, in dem die Seitenleiste geöffnet werden soll.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Returns
-
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()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Konfiguriert die Seitenleiste.
Parameter
-
Optionen
Die Konfigurationsoptionen, die auf den Bereich angewendet werden sollen.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Returns
-
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()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Konfiguriert das Verhalten der Seitenleiste der Erweiterung. Dies ist ein Upsert-Vorgang.
Parameter
-
zum weltweiten Kundenverhalten.
Das festzulegende neue Verhalten.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Returns
-
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.