Opis
Używaj interfejsu API chrome.sidePanel
do hostowania treści w panelu bocznym przeglądarki obok głównej treści strony internetowej.
Uprawnienia
sidePanel
Aby używać interfejsu Side Panel API, dodaj uprawnienie "sidePanel"
do pliku manifest rozszerzenia:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Dostępność
Pojęcia i wykorzystanie
Interfejs Side Panel API umożliwia rozszerzeniom wyświetlanie własnego interfejsu w panelu bocznym, zapewniając użytkownikom nieprzerwany komfort korzystania z internetu.
![Menu w panelu bocznym](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/example-side-panel.png?authuser=19&hl=pl)
Oto niektóre funkcje:
- Panel boczny pozostaje otwarty podczas przechodzenia między kartami (jeśli jest tak ustawiony).
- Może być dostępny tylko na określonych stronach.
- Panele boczne pełnią rolę strony rozszerzenia i 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.
Przypadki użycia
W sekcjach poniżej znajdziesz typowe przypadki użycia interfejsu Side Panel API. Pełne przykłady rozszerzeń znajdziesz w sekcji Przykłady rozszerzeń.
Wyświetlanie tego samego panelu bocznego w każdej witrynie
Aby wyświetlać ten sam panel boczny w każdej witrynie, możesz początkowo użyć właściwości "default_path"
w kluczu "side_panel"
pliku manifestu. Powinien on wskazywać ścieżkę względną w katalogu rozszerzenia.
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żywać sidepanel.setOptions()
, aby włączyć panel boczny na określonej karcie. W tym przykładzie użyto chrome.tabs.onUpdated()
do nasłuchiwania zmian wprowadzonych na karcie. Sprawdza, czy adres URL to www.google.com, i włącza panel boczny. W przeciwnym razie funkcja 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ę, na której panel boczny nie jest włączony, panel boczny zostanie ukryty. Wyświetli się automatycznie, gdy użytkownik przejdzie na kartę, na której była wcześniej otwarta.
Gdy użytkownik otworzy witrynę, w której panel boczny nie jest włączony, panel się zamknie, a rozszerzenie nie będzie widoczne w menu.
Pełny przykład znajdziesz w przykładzie panelu bocznego dotyczącego karty.
Otwórz panel boczny, klikając ikonę na pasku narzędzi
Deweloperzy mogą zezwolić użytkownikom na otwarcie panelu bocznego po kliknięciu ikony działania z ikoną sidePanel.setPanelBehavior()
na pasku narzędzi. Najpierw zadeklaruj klucz "action"
w pliku manifestu:
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
Chrome 116 wprowadza sidePanel.open()
. Umożliwia rozszerzeniom otwieranie panelu bocznego przez gest użytkownika, np. kliknięcie ikony działania. Albo interakcja użytkownika na stronie rozszerzenia lub skrypcie treści, np. kliknięcie przycisku. Pełną wersję demonstracyjną znajdziesz w przykładowym rozszerzeniu Otwórz panel boczny.
Ten kod pokazuje, jak otworzyć globalny panel boczny w bieżącym oknie, gdy użytkownik kliknie menu kontekstowe. Jeśli używasz elementu sidePanel.open()
, musisz wybrać kontekst, w którym ma się otworzyć. Użyj narzędzia windowId
, aby otworzyć globalny panel boczny. Możesz też ustawić tabId
tak, aby otwierał panel boczny 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ą sidepanel.getOptions()
. Ten przykład ustawia powitalny panel boczny w runtime.onInstalled()
. Gdy użytkownik przejdzie na inną kartę, zastąpi ją 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.
Interfejs boczny panelu bocznego
Użytkownicy najpierw zobaczą panele boczne wbudowane w Chrome. W każdym panelu bocznym w menu jest wyświetlana ikona rozszerzenia. Jeśli nie zostaną uwzględnione żadne 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 kombinacji ikony działania
dzięki sidePanel.setPanelBehavior()
. Możesz też zadzwonić pod numer sidePanel.open()
po interakcji użytkownika, na przykład:
- Kliknięcie w działaniach.
- skrótu klawiszowego.
- menu kontekstowego.
- Gest użytkownika na stronie rozszerzenia lub skrypcie treści.
Przypnij panel boczny
![Ikona pinezki w interfejsie panelu bocznego.](https://developer.chrome.com/static/docs/extensions/reference/api/sidePanel/images/side-panel-pin.png?authuser=19&hl=pl)
Gdy panel boczny jest otwarty, na pasku narzędzi panelu bocznego wyświetla się ikona pinezki. Kliknięcie ikony przypina ikonę działania rozszerzenia. Kliknięcie ikony czynności będzie wykonywać domyślne działanie dla ikony działania i tylko otwórz panel boczny, jeśli został on jawnie skonfigurowany.
Przykłady
Więcej wersji demonstracyjnych rozszerzeń interfejsu Side Panel API znajdziesz w tych wersjach:
- 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 wartość, zostaną zwrócone opcje panelu bocznego dla danej karty. W przeciwnym razie zwraca domyślne opcje panelu bocznego (używane na każdej karcie, która nie ma określonych ustawień).
OpenOptions
Właściwości
-
tabId
liczba opcjonalnie
Karta, na której otwiera się panel boczny. Jeśli dana karta ma własny panel boczny, będzie on otwarty tylko dla tej karty. Jeśli nie ma panelu odnoszącego się do konkretnej karty, panel globalny będzie otwarty na określonej karcie oraz w innych kartach, które nie mają jeszcze otwartego panelu. Spowoduje to zastąpienie wszystkich aktywnych obecnie paneli bocznych (globalnych lub związanych z kartami) na odpowiedniej karcie. Należy podać co najmniej 1 z tych elementów lub
windowId
. -
windowId
liczba opcjonalnie
Okno, w którym otwiera się panel boczny. Ma to zastosowanie tylko wtedy, gdy rozszerzenie ma globalny panel boczny (niezwiązany z kartami) lub określono też
tabId
. Spowoduje to zastąpienie każdego aktywnego globalnego panelu bocznego otwartego przez użytkownika w danym oknie. Należy podać co najmniej 1 z tych elementów lubtabId
.
PanelBehavior
Właściwości
-
openPanelOnActionClick
Wartość logiczna opcjonalna
Kliknięcie ikony rozszerzenia spowoduje przełączenie jego wyświetlania 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. Nie jest to jednak wymagane. 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 w panelu bocznym, będą one stosowane tylko na karcie o tym identyfikatorze. Pominięcie tych opcji ustawia działanie domyślne (używane w przypadku wszystkich kart, które nie mają określonych ustawień). Uwaga: jeśli masz ustawioną tę samą ścieżkę dla tego identyfikatora karty i domyślnego tabId, panel dla tego parametru będzie inną instancją niż panel domyślnego identyfikatora tabId.
SidePanel
Właściwości
-
default_path
ciąg znaków
Ścieżka podana przez dewelopera do wyświetlania panelu bocznego.
Metody
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Zwraca konfigurację aktywnego panelu.
Parametry
-
Opcje
Określa kontekst, dla którego ma zostać zwrócona konfiguracja.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(options: PanelOptions) => void
-
Opcje
-
Zwroty
-
Promise<PanelOptions>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Zwraca obecne działanie panelu bocznego rozszerzenia.
Parametry
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:(behavior: PanelBehavior) => void
-
o zachowaniach konsumentów
-
Zwroty
-
Promise<PanelBehavior>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Otwiera panel boczny rozszerzenia. Tę funkcję można wywołać tylko w odpowiedzi na działanie użytkownika.
Parametry
-
Opcje
Określa kontekst, w którym należy otworzyć panel boczny.
-
wywołanie zwrotne
funkcja optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane 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 optional
Parametr
callback
wygląda tak:() => void
Zwroty
-
Obietnica<void>
Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.