chrome.sidePanel

Opis

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

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 nowszy MV3 lub nowszy

Pojęcia i zastosowanie

Interfejs Side Panel API umożliwia rozszerzeniom wyświetlanie własnego interfejsu w panelu bocznym, co pozwala na zapewnienie użytkownikom stałych funkcji uzupełniających proces przeglądania.

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

Oto niektóre z nich:

  • Panel boczny pozostaje otwarty podczas przechodzenia między kartami (jeśli tak ustawisz).
  • Może być dostępna tylko w określonych witrynach.
  • 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.

Przypadki użycia

W sekcjach poniżej przedstawiamy kilka typowych przypadków 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

Panel boczny można początkowo ustawić 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. 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 w określonej witrynie

Rozszerzenie może używać interfejsu API sidepanel.setOptions(), aby włączyć panel boczny na określonej karcie. W tym przykładzie używamy chrome.tabs.onUpdated(), aby nasłuchiwać wszelkich 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';

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. Automatycznie pojawi się 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 będzie widoczne w menu panelu bocznego.

Pełny przykład znajdziesz w sekcji Panel boczny dotyczący 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łania 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
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Programowe otwieranie panelu bocznego w wyniku interakcji użytkownika

W Chrome 116 wprowadziliśmy sidePanel.open(). Umożliwia rozszerzeniom otwieranie panelu bocznego za pomocą gestu użytkownika, np. kliknięcia 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ładzie rozszerzenia Open Side Panel (Otwórz panel boczny).

Poniższy kod pokazuje, jak otworzyć globalny panel boczny w bieżącym oknie, gdy użytkownik kliknie menu kontekstowe. Podczas korzystania z gestu 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 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łączanie się na inny panel

Rozszerzenia mogą używać funkcji sidepanel.getOptions() do pobierania bieżącego panelu bocznego. W tym przykładzie ustawiamy panel boczny z powitaniem na stronie 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.

Wrażenia użytkowników w przypadku panelu bocznego

Użytkownicy najpierw zobaczą wbudowane panele boczne Chrome. W menu panelu bocznego każdego rozszerzenia wyświetla się jego ikona. Jeśli nie ma żadnych ikon, wyświetli się ikona zastępcza z pierwszą literą nazwy rozszerzenia.

Otwórz panel boczny

Aby zezwolić użytkownikom na otwieranie panelu bocznego, użyj ikony działania w połączeniu z sidePanel.setPanelBehavior(). Możesz też wykonać połączenie z numerem sidePanel.open() po interakcji użytkownika, np.:

Przypinanie panelu bocznego

Ikona przypinania 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 ikony działania po jej przypięciu spowoduje wykonanie domyślnego działania przypisanego do tej ikony. Panel boczny otworzy się tylko wtedy, gdy zostało to wyraźnie skonfigurowane.

Przykłady

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

Typy

CloseOptions

Oczekuje

Właściwości

  • tabId

    number opcjonalny

    Karta, na której ma zostać zamknięty panel boczny. Jeśli w określonej karcie jest otwarty panel boczny dotyczący tej karty, zostanie on zamknięty. Musisz podać co najmniej jeden z tych kodów lub windowId.

  • windowId

    number opcjonalny

    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 dotyczący karty. Musisz podać co najmniej jeden z tych kodów lub tabId.

GetPanelOptions

Właściwości

  • tabId

    number opcjonalny

    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 wszystkich kart, które nie mają określonych ustawień).

OpenOptions

Chrome 116 lub nowsza

Właściwości

  • tabId

    number opcjonalny

    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 przypisanego do karty, panel globalny otworzy się na określonej karcie i na wszystkich innych kartach, na których nie ma obecnie otwartego panelu przypisanego do karty. Spowoduje to zastąpienie dowolnego aktywnego panelu bocznego (globalnego lub dotyczącego karty) na odpowiedniej karcie. Musisz podać co najmniej jeden z tych kodów lub windowId.

  • windowId

    number opcjonalny

    Okno, w którym ma się otworzyć panel boczny. Dotyczy to tylko sytuacji, gdy rozszerzenie ma globalny (niezależny od karty) panel boczny lub gdy określono też tabId. Spowoduje to zastąpienie dowolnego aktywnego obecnie globalnego panelu bocznego otwartego przez użytkownika w danym oknie. Musisz podać co najmniej jeden z tych kodów lub tabId.

PanelBehavior

Właściwości

  • openPanelOnActionClick

    wartość logiczna opcjonalna

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

PanelLayout

Oczekuje

Właściwości

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

    string opcjonalny

    Ścieżka do pliku HTML panelu bocznego, który ma być używany. Musi to być lokalny zasób w pakiecie rozszerzenia.

  • tabId

    number opcjonalny

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

Side

Oczekuje

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

Typ wyliczeniowy

„left”

„right”

SidePanel

Właściwości

  • default_path

    ciąg znaków

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

Metody

getLayout()

Oczekuje
chrome.sidePanel.getLayout(): Promise<PanelLayout>

Zwraca bieżący układ panelu bocznego.

Zwroty

getOptions()

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

Zwraca aktywną konfigurację panelu.

Parametry

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

Zwroty

getPanelBehavior()

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

Zwraca bieżące zachowanie panelu bocznego rozszerzenia.

Zwroty

open()

Chrome 116 lub nowsza 
chrome.sidePanel.open(
  options: OpenOptions,
): Promise<void>

Otwiera panel boczny rozszerzenia. Tę funkcję można wywołać tylko w odpowiedzi na działanie użytkownika.

Parametry

  • Opcje

    OpenOptions

    Określa kontekst, w którym ma się otworzyć panel boczny.

Zwroty

  • Promise<void>

setOptions()

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

Konfiguruje panel boczny.

Parametry

  • Opcje

    PanelOptions

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

Zwroty

  • Promise<void>

setPanelBehavior()

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

Konfiguruje działanie panelu bocznego rozszerzenia. Jest to operacja typu upsert.

Parametry

  • o zachowaniach konsumentów

    PanelBehavior

    Nowe zachowanie do ustawienia.

Zwroty

  • Promise<void>