browser.sidePanel

Opis

Użyj interfejsu API chrome.sidePanel, aby hostować treści w panelu bocznym przeglądarki obok głównej zawartości strony internetowej.

Uprawnienia

sidePanel

Aby używać interfejsu Side Panel API, dodaj uprawnienie "sidePanel" w pliku manifestu rozszerzenia:

manifest.json:

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

Dostępność

Chrome 114 lub nowsza browser.* od Chrome 148 MV3 lub nowsza

Pojęcia i użycie

Interfejs Side Panel API umożliwia rozszerzeniom wyświetlanie własnego interfejsu w panelu bocznym, co pozwala na stałe uzupełnianie procesu przeglądania.

Menu w panelu bocznym
Interfejs panelu bocznego przeglądarki Chrome.

Oto niektóre z funkcji:

  • Panel boczny pozostaje otwarty podczas przechodzenia między kartami (jeśli jest tak ustawiony).
  • Może być dostępna tylko na określonych stronach internetowych.
  • Panele boczne, jako strony rozszerzeń, 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 przedstawiamy kilka typowych zastosowań interfejsu Side Panel API. Przykłady pełnych rozszerzeń znajdziesz w sekcji Przykłady rozszerzeń.

Wyświetlanie tego samego panelu bocznego w każdej witrynie

Panel boczny można początkowo ustawić we właściwości "default_path" w kluczu "side_panel" pliku manifestu, aby wyświetlać ten sam panel boczny w każdej witrynie. Powinna ona 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 na określonej stronie

Rozszerzenie może używać sidepanel.setOptions(), aby włączyć panel boczny na określonej karcie. W tym przykładzie używamy browser.tabs.onUpdated(), aby nasłuchiwać aktualizacji wprowadzonych na karcie. Sprawdza, czy adres URL to www.google.com, i włącza panel boczny. W przeciwnym razie wyłącza tę funkcję.

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
    });
  }
});

Gdy użytkownik tymczasowo przełączy się na kartę, na której panel boczny nie jest włączony, panel boczny zostanie ukryty. Pojawi się on automatycznie, gdy użytkownik przełączy się na kartę, na której był wcześniej otwarty.

Gdy użytkownik przejdzie do witryny, w której panel boczny nie jest włączony, panel boczny zostanie zamknięty, a rozszerzenie nie będzie widoczne w menu panelu bocznego.

Pełny przykład znajdziesz w sekcji Panel boczny karty.

Otwórz panel boczny, klikając ikonę na pasku narzędzi.

Deweloperzy mogą zezwolić użytkownikom na otwieranie panelu bocznego po kliknięciu ikony paska narzędzi działań za pomocą sidePanel.setPanelBehavior(). 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
browser.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Programowe otwieranie panelu bocznego podczas interakcji użytkownika

W Chrome 116 wprowadziliśmy sidePanel.open(). Umożliwia rozszerzeniom otwieranie panelu bocznego za pomocą gestu użytkownika, takiego jak kliknięcie ikony działania. Może to być też interakcja użytkownika na stronie rozszerzenia lub w skrypcie treści, np. kliknięcie przycisku. Pełną wersję demonstracyjną znajdziesz w przykładowym rozszerzeniu Otwórz panel boczny.

Poniższy kod pokazuje, jak otworzyć globalny panel boczny w bieżącym oknie, gdy użytkownik kliknie menu kontekstowe. Gdy używasz sidePanel.open(), musisz wybrać kontekst, w którym ma się otworzyć. Użyj skrótu windowId, aby otworzyć globalny panel boczny. Możesz też ustawić tabId, aby otwierać panel boczny tylko na określonej karcie.

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 });
  }
});

Przełączanie się na inny panel

Rozszerzenia mogą używać sidepanel.getOptions() do pobierania bieżącego panelu bocznego. Ten przykład ustawia panel boczny powitania na stronie runtime.onInstalled(). Gdy użytkownik przejdzie na inną kartę, zostanie ona zastąpiona głównym panelem bocznym.

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 });
  }
});

Pełny kod znajdziesz w przykładzie Wiele paneli bocznych.

Panel boczny

Użytkownicy najpierw zobaczą wbudowane panele boczne Chrome. W menu panelu bocznego wyświetla się ikona rozszerzenia. Jeśli nie ma żadnych ikon, wyświetli 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 sidePanel.setPanelBehavior(). Możesz też wywołać funkcję sidePanel.open() po interakcji użytkownika, np.:

Przypinanie panelu bocznego

Ikona pinezki w interfejsie panelu bocznego.
Ikona przypinania w interfejsie panelu bocznego.

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 przypiętej ikony działania spowoduje wykonanie domyślnego działania dla tej ikony i otworzy panel boczny tylko wtedy, gdy zostało to wyraźnie skonfigurowane.

Przykłady

Więcej wersji demonstracyjnych rozszerzeń interfejsu Side Panel API znajdziesz w tych rozszerzeniach:

Typy

CloseOptions

Chrome 141 lub nowsza wersja browser.* od Chrome 148

Właściwości

  • tabId

    number optional

    Karta, na której chcesz zamknąć panel boczny. Jeśli na określonej karcie jest otwarty panel boczny, zostanie on zamknięty. Jeśli otwarty jest tylko globalny panel boczny, obietnica zwrócona przez wywołanie funkcji close() zostanie odrzucona z błędem. To zachowanie zostało zmienione w Chrome 145. W poprzednich wersjach panel globalny był zamykany. Musisz podać co najmniej tę właściwość lub windowId.

  • windowId

    number optional

    Okno, w którym ma zostać zamknięty panel boczny. Jeśli w określonym oknie jest otwarty globalny panel boczny, zostanie on zamknięty na wszystkich kartach w tym oknie, na których nie jest aktywny panel boczny karty. Musisz podać co najmniej tę właściwość lub tabId.

GetPanelOptions

Właściwości

  • tabId

    number optional

    Jeśli zostanie określony, zostaną zwrócone opcje panelu bocznego dla danej karty. W przeciwnym razie zwraca domyślne opcje panelu bocznego (używane w przypadku kart, które nie mają określonych ustawień).

OpenOptions

Chrome 116 lub nowsza wersja browser.* od Chrome 148

Właściwości

  • tabId

    number optional

    Karta, na której ma się otworzyć panel boczny. Jeśli odpowiednia karta ma panel boczny, będzie on otwarty tylko na tej karcie. Jeśli nie ma panelu dla konkretnej karty, panel globalny zostanie otwarty na określonej karcie i na wszystkich innych kartach, na których nie ma obecnie otwartego panelu dla konkretnej karty. Spowoduje to zastąpienie wszystkich aktywnych paneli bocznych (globalnych lub związanych z kartą) na odpowiedniej karcie. Musisz podać co najmniej tę właściwość lub windowId.

  • windowId

    number optional

    Okno, w którym ma zostać otwarty panel boczny. Ma to zastosowanie tylko wtedy, gdy rozszerzenie ma panel boczny globalny (niezależny od karty) lub gdy określono też tabId. Spowoduje to zastąpienie wszystkich aktywnych globalnych paneli bocznych, które użytkownik ma otwarte w danym oknie. Musisz podać co najmniej tę właściwość lub tabId.

PanelBehavior

Właściwości

  • openPanelOnActionClick

    boolean opcjonalne

    Określa, czy kliknięcie ikony rozszerzenia spowoduje przełączenie wyświetlania wpisu rozszerzenia w panelu bocznym. Wartość domyślna to fałsz.

PanelClosedInfo

Chrome 142 lub nowsza wersja browser.* od Chrome 148

Właściwości

  • ścieżka

    tekst

    Ścieżka zasobu lokalnego w pakiecie rozszerzenia, którego zawartość jest wyświetlana w panelu.

  • tabId

    number optional

    Opcjonalny identyfikator karty, na której zamknięto panel boczny. Te informacje są podawane tylko wtedy, gdy panel jest powiązany z kartą.

  • windowId

    liczba

    Identyfikator okna, w którym zamknięto panel boczny. Ta opcja jest dostępna zarówno w przypadku paneli globalnych, jak i paneli na kartach.

PanelLayout

Chrome 140 lub nowsza browser.* od Chrome 148

Właściwości

PanelOpenedInfo

Chrome 141 lub nowsza wersja browser.* od Chrome 148

Właściwości

  • ścieżka

    tekst

    Ścieżka zasobu lokalnego w pakiecie rozszerzenia, którego zawartość jest wyświetlana w panelu.

  • tabId

    number optional

    Opcjonalny identyfikator karty, na której otwarty jest panel boczny. Te informacje są podawane tylko wtedy, gdy panel jest powiązany z kartą.

  • windowId

    liczba

    Identyfikator okna, w którym otwarty jest panel boczny. Ta opcja jest dostępna zarówno w przypadku paneli globalnych, jak i paneli na kartach.

PanelOptions

Właściwości

  • aktywne

    boolean opcjonalne

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

  • tabId

    number optional

    Jeśli ta opcja jest określona, opcje panelu bocznego będą stosowane tylko do karty o tym identyfikatorze. Jeśli te opcje zostaną pominięte, ustawią działanie domyślne (używane w przypadku każdej karty, która nie ma określonych ustawień). Uwaga: jeśli dla tego identyfikatora tabId i domyślnego identyfikatora tabId ustawiono tę samą ścieżkę, panel dla tego identyfikatora tabId będzie inną instancją niż panel dla domyślnego identyfikatora tabId.

Side

Chrome 140 lub nowsza browser.* od Chrome 148

Określa możliwe wyrównanie panelu bocznego w interfejsie przeglądarki.

Typ wyliczeniowy

"left"

"right"

SidePanel

Właściwości

  • default_path

    tekst

    Ścieżka określona przez dewelopera do wyświetlania panelu bocznego.

Metody

close()

Chrome 141 lub nowsza wersja browser.* od Chrome 148 
browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

Zamyka panel boczny rozszerzenia. Jeśli panel jest już zamknięty, nie zostanie wykonane żadne działanie.

Parametry

  • Opcje

    CloseOptions

    Określa kontekst, w którym panel boczny ma zostać zamknięty.

Zwroty

  • thought Promise<void>

    Zwraca obietnicę, która jest spełniana po zamknięciu panelu bocznego.

getLayout()

Chrome 140 lub nowsza browser.* od Chrome 148 
browser.sidePanel.getLayout(): Promise<PanelLayout>

Zwraca bieżący układ panelu bocznego.

Zwroty

getOptions()

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

Zwraca konfigurację aktywnego panelu.

Parametry

  • Określa kontekst, dla którego ma zostać zwrócona konfiguracja.

Zwroty

  • Promise<PanelOptions>

    Zwraca obiekt Promise, który rozwiązuje się z aktywną konfiguracją panelu.

getPanelBehavior()

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

Zwraca bieżące działanie panelu bocznego rozszerzenia.

Zwroty

  • Promise<PanelBehavior>

    Zwraca obiekt Promise, który rozwiązuje problem z zachowaniem panelu bocznego rozszerzenia.

open()

Chrome 116 lub nowsza wersja browser.* od Chrome 148 
browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

Otwiera panel boczny rozszerzenia. Można to wywołać tylko w odpowiedzi na działanie użytkownika.

Parametry

  • Opcje

    OpenOptions

    Określa kontekst, w którym ma zostać otwarty panel boczny.

Zwroty

  • thought Promise<void>

    Zwraca obiekt Promise, który jest rozwiązywany po otwarciu panelu bocznego.

setOptions()

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

Konfiguruje panel boczny.

Parametry

  • Opcje

    PanelOptions

    Opcje konfiguracji, które mają zostać zastosowane do panelu.

Zwroty

  • thought Promise<void>

    Zwraca obiekt Promise, który jest rozwiązywany po ustawieniu opcji.

setPanelBehavior()

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

Konfiguruje działanie panelu bocznego rozszerzenia. Jest to operacja aktualizacji i wstawiania.

Parametry

  • o zachowaniach konsumentów

    PanelBehavior

    Nowe zachowanie, które ma zostać ustawione.

Zwroty

  • thought Promise<void>

    Zwraca obietnicę, która jest spełniana po ustawieniu nowego działania.

Wydarzenia

onClosed

Chrome 142 lub nowsza wersja browser.* od Chrome 148 
browser.sidePanel.onClosed.addListener(
  callback: function,
)

Uruchamiane, gdy panel boczny rozszerzenia jest zamknięty.

Parametry

onOpened

Chrome 141 lub nowsza wersja browser.* od Chrome 148 
browser.sidePanel.onOpened.addListener(
  callback: function,
)

Uruchamiane po otwarciu panelu bocznego rozszerzenia.

Parametry