Opis
Interfejs API chrome.sidePanel
umożliwia przechowywanie treści w panelu bocznym przeglądarki razem z główną treścią strony internetowej.
Uprawnienia
sidePanel
Aby korzystać z interfejsu Side Panel API, dodaj uprawnienie "sidePanel"
w pliku manifestu rozszerzenia:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Dostępność
Pojęcia i zastosowanie
Interfejs Side Panel API pozwala rozszerzeniom wyświetlać w panelu bocznym własny interfejs użytkownika, a tym samym wzbogacać wrażenia użytkownika podczas przeglądania internetu.
Oto niektóre funkcje:
- Panel boczny pozostaje otwarty podczas przechodzenia między kartami (jeśli jest włączony).
- Może być dostępna tylko na określonych stronach internetowych.
- Jako strona rozszerzenia panele boczne mają dostęp do wszystkich interfejsów API Chrome.
- W ustawieniach Chrome użytkownicy mogą określić, po której stronie ma być wyświetlany panel.
Przykłady zastosowań
W sekcjach poniżej znajdziesz kilka typowych przypadków użycia interfejsu Side Panel API. Całe przykłady rozszerzeń znajdziesz w sekcji Przykłady rozszerzeń.
Wyświetlaj ten sam panel boczny w każdej witrynie
Panel boczny można skonfigurować początkowo za pomocą właściwości "default_path"
w kluczu "side_panel"
pliku manifestu, aby wyświetlał ten sam panel boczny w każdej witrynie. Powinien on wskazywać ścieżkę względną w katalogu rozszerzeń.
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>
Włączanie panelu bocznego w określonej witrynie
Rozszerzenie może użyć sidepanel.setOptions()
, aby włączyć panel boczny na określonej karcie. W tym przykładzie użyto chrome.tabs.onUpdated()
do nasłuchiwania aktualizacji karty. Sprawdza, czy adres URL to www.google.com, i włącza panel boczny. W przeciwnym razie zostanie wyłączona.
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
});
}
});
Gdy użytkownik tymczasowo przełączy się na kartę, która nie ma włączonego panelu bocznego, panel boczny będzie ukryty. Zostanie ona automatycznie wyświetlona ponownie, gdy użytkownik przełączy się na kartę, na której była wcześniej otwarta.
Gdy użytkownik przejdzie do witryny, w której panel boczny nie jest włączony, panel boczny zostanie zamknięty, a rozszerzenie nie pojawi się w menu.
Pełny przykład znajdziesz w przykładzie panelu bocznego dotyczącego karty.
Otwórz panel boczny, klikając ikonę paska narzędzi
Deweloperzy mogą zezwolić użytkownikom na otwieranie panelu bocznego po kliknięciu ikony działania na pasku narzędzi sidePanel.setPanelBehavior()
. Najpierw zadeklaruj w pliku manifestu klucz "action"
:
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
Teraz dodaj ten kod do poprzedniego przykładu:
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));
...
Automatyczne otwieranie panelu bocznego przy interakcji użytkownika
W Chrome 116 wprowadzamy sidePanel.open()
. Umożliwia rozszerzeniom otwieranie panelu bocznego przez gest użytkownika, na przykład kliknięcie ikony działania. Interakcja użytkownika ze stroną rozszerzenia lub skryptem treści, na przykład kliknięcie przycisku. Pełną prezentację znajdziesz w przykładowym rozszerzeniu do Otwórz panel boczny.
Poniższy kod pokazuje, jak otworzyć globalny panel boczny w bieżącym oknie, gdy użytkownik kliknie menu kontekstowe. Jeśli używasz sidePanel.open()
, musisz wybrać kontekst, w którym ma się ona otworzyć. Użyj narzędzia windowId
, aby otworzyć globalny panel boczny. Możesz też skonfigurować tabId
w taki sposób, aby panel boczny otwierał się tylko na określonej karcie.
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 });
}
});
Przełącz na inny panel
Rozszerzenia mogą pobierać bieżący panel boczny za pomocą polecenia sidepanel.getOptions()
. Ten przykład pokazuje powitanie panelu bocznego w domenie runtime.onInstalled()
. Gdy użytkownik przejdzie na inną kartę, zastąpi ją główny panel boczny.
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 });
}
});
Pełny kod znajdziesz w przykładzie Wiele paneli bocznych.
Wygoda korzystania z panelu bocznego
Użytkownicy najpierw zobaczą wbudowane panele boczne Chrome. W każdym panelu bocznym wyświetla się ikona rozszerzenia w menu panelu bocznego. Jeśli nie dodasz żadnej ikony, pojawi się ikona zastępcza z pierwszą literą nazwy rozszerzenia.
Otwórz panel boczny
Aby umożliwić użytkownikom otwieranie panelu bocznego, użyj ikony działania w połączeniu z ikoną sidePanel.setPanelBehavior()
. Możesz też zadzwonić pod numer sidePanel.open()
po interakcji użytkownika, na przykład:
- kliknięciem działania,
- Skrótu klawiszowego.
- menu kontekstowego;
- Gest użytkownika na stronie rozszerzenia lub w skrypcie treści.
Przypnij panel boczny
Gdy panel boczny jest otwarty, na pasku narzędzi w panelu bocznym wyświetla się ikona pinezki. Kliknięcie ikony przypina ikonę działania rozszerzenia. Kliknięcie przypiętej ikony działania spowoduje uruchomienie domyślnego działania związanego z ikoną działania i otworzy panel boczny tylko wtedy, gdy zostanie on wyraźnie skonfigurowany.
Przykłady
Aby zobaczyć więcej demonstracji rozszerzeń interfejsu Side Panel API, wypróbuj te rozszerzenia:
- Panel boczny słownika.
- Globalny panel boczny
- Wiele paneli bocznych.
- Otwórz panel boczny.
- Panel boczny dotyczący konkretnej witryny
Typy
GetPanelOptions
Właściwości
-
tabId
Liczba opcjonalnie
Jeśli określisz opcje panelu bocznego, dla danej karty zostaną zwrócone opcje. W przeciwnym razie zwraca domyślne opcje panelu bocznego (używane w przypadku każdej karty, która nie ma określonych ustawień).
OpenOptions
Właściwości
-
tabId
Liczba opcjonalnie
Karta, na której chcesz otworzyć panel boczny. Jeśli dana karta ma panel boczny określonej karty, będzie on otwarty tylko dla tej karty. Jeśli na danej karcie nie ma panelu, panel globalny będzie otwarty na określonej karcie i wszelkich innych kartach, które nie zawierają aktualnie otwartego panelu na tej karcie. Spowoduje to zastąpienie każdego aktywnego panelu bocznego (globalnego lub dotyczącego danej karty) na odpowiedniej karcie. Należy podać co najmniej jedną z tych wartości lub
windowId
. -
windowId
Liczba opcjonalnie
Okno, w którym ma zostać otwarty panel boczny. Ma to zastosowanie tylko wtedy, gdy rozszerzenie ma globalny panel boczny (niezwiązany z określoną kartą) lub określono też atrybut
tabId
. Spowoduje to zastąpienie każdego aktywnego globalnego panelu bocznego, który użytkownik otworzył w danym oknie. Należy podać co najmniej jedną z tych wartości lubtabId
.
PanelBehavior
Właściwości
-
openPanelOnActionClick
wartość logiczna opcjonalna
Określa, czy kliknięcie ikony rozszerzenia spowoduje wyświetlanie wpisu rozszerzenia w panelu bocznym. Wartość domyślna to fałsz.
PanelOptions
Właściwości
-
włączone
wartość logiczna opcjonalna
Określa, czy panel boczny ma być włączony. To pole jest opcjonalne. Wartość domyślna to true (prawda).
-
ścieżka
ciąg znaków opcjonalny
Ścieżka do pliku HTML panelu bocznego, którego chcesz użyć. Musi to być zasób lokalny w pakiecie rozszerzeń.
-
tabId
Liczba opcjonalnie
Jeśli określisz opcje panelu bocznego, będą one miały zastosowanie tylko do karty o tym identyfikatorze. W przypadku pominięcia tej opcji opcje te ustawiają działanie domyślne (stosowane w przypadku kart, które nie mają konkretnych ustawień). Uwaga: jeśli dla tego identyfikatora tabId i domyślnego identyfikatora tabId ustawisz tę samą ścieżkę, panel dla tego identyfikatora tabId będzie inny niż panel domyślnego identyfikatora tabId.
SidePanel
Właściwości
-
default_path
string,
Ścieżka wyświetlania panelu bocznego określona przez programistę.
Metody
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Zwraca aktywną konfigurację panelu.
Parametry
-
Opcje
Określa kontekst, w którego przypadku ma zostać zwrócona konfiguracja.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(options: PanelOptions) => void
-
Opcje
-
Zwroty
-
Promise<PanelOptions>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Zwraca aktualne działanie panelu bocznego.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(behavior: PanelBehavior) => void
-
o zachowaniach konsumentów
-
Zwroty
-
Promise<PanelBehavior>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Otwiera panel boczny rozszerzenia. To ustawienie można wywołać tylko w odpowiedzi na działanie użytkownika.
Parametry
-
Opcje
Określa kontekst, w którym ma zostać otwarty panel boczny.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Konfiguruje panel boczny.
Parametry
-
Opcje
Opcje konfiguracji, które mają być stosowane do panelu.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Konfiguruje działanie panelu bocznego rozszerzenia. To jest operacja upsert.
Parametry
-
o zachowaniach konsumentów
Nowe zachowanie do ustawienia.
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.