chrome.sidePanel

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

Chrome w wersji 114 lub nowszej MV3 lub nowszy

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
Interfejs panelu bocznego przeglądarki Chrome.

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:

Przypnij panel boczny

Ikona pinezki w interfejsie panelu bocznego.
Ikona pinezki 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 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:

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

Chrome 116 lub nowszy .

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

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

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

Zwraca konfigurację aktywnego panelu.

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (options: PanelOptions) => void

Zwroty

  • Promise&lt;PanelOptions&gt;

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

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

Zwroty

  • Promise&lt;PanelBehavior&gt;

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

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

    OpenOptions

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

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

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