chrome.sidePanel

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ść

Chrome 114 i nowsze MV3 i nowsze

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.

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

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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Pełną próbkę znajdziesz w sekcji 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

Przechodzenie do menu panelu bocznego
Użytkownicy mogą znaleźć dostępne panele boczne w menu panelu bocznego. Następnie może wybrać rozszerzenie z menu.
Menu w panelu bocznym
Interfejs panelu bocznego przeglądarki Chrome.
Otwieranie gestem użytkownika

Panel boczny możesz otworzyć poprzez interakcje użytkowników za pomocą narzędzi sidePanel.open() i sidePanel.setPanelBehavior(), na przykład:

Przykłady

Aby zobaczyć więcej demonstracji rozszerzeń interfejsu Side Panel API, wypróbuj te rozszerzenia:

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

Chrome 116 i nowsze wersje

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 lub tabId.

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. 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 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()

Obietnica 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Zwraca aktywną konfigurację panelu.

Parametry

  • 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

Akcje powrotne

  • 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()

Obietnica 
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

Akcje powrotne

  • 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()

Obietnica Chrome w wersji 116 lub nowszej 
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

    OpenOptions

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • 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()

Obietnica 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Konfiguruje panel boczny.

Parametry

  • Opcje

    PanelOptions

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • 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()

Obietnica 
chrome.sidePanel.setPanelBehavior(
  behavior: PanelBehavior,
  callback?: function,
)

Konfiguruje działanie panelu bocznego rozszerzenia. To jest operacja upsert.

Parametry

  • o zachowaniach konsumentów

    PanelBehavior

    Nowe zachowanie do ustawienia.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

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