browser.sidePanel

Beschrijving

Gebruik de chrome.sidePanel API om content te hosten in het zijvenster van de browser naast de hoofdcontent van een webpagina.

Rechten

sidePanel

Als je de Side Panel API wilt gebruiken, voeg je het recht "sidePanel" toe aan het manifestbestand van de extensie:

manifest.json:

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

Beschikbaarheid

Chrome 114+ MV3+

Concepten en gebruik

Met de Side Panel API kunnen extensies hun eigen UI tonen in het zijvenster, zodat gebruikers een consistente ervaring hebben die hun browseproces aanvult.

Dropdownmenu in zijvenster
UI van het zijvenster van de Chrome-browser.

Enkele functies:

  • Het zijvenster blijft open als je tussen tabbladen navigeert (als je dit zo hebt ingesteld).
  • De functie is misschien alleen beschikbaar op specifieke websites.
  • Als extensiepagina hebben zijvensters toegang tot alle Chrome API's.
  • In de instellingen van Chrome kunnen gebruikers aangeven aan welke kant het deelvenster moet worden getoond.

Toepassingen

In de volgende gedeelten worden enkele veelvoorkomende toepassingen van de Side Panel API beschreven. Ga naar Voorbeelden van extensies voor volledige voorbeelden van extensies.

Hetzelfde zijvenster op elke site tonen

Het zijvenster kan in eerste instantie worden ingesteld via de property "default_path" in de sleutel "side_panel" van het manifest om hetzelfde zijvenster op elke site te tonen. Dit moet verwijzen naar een relatief pad in de extensiemap.

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>

Een zijvenster aanzetten op een specifieke site

Een extensie kan sidepanel.setOptions() gebruiken om een zijvenster aan te zetten op een specifiek tabblad. In dit voorbeeld wordt browser.tabs.onUpdated() gebruikt om te luisteren naar updates die op het tabblad worden aangebracht. De extensie checkt of de URL www.google.com is en zet het zijvenster aan. Anders wordt de functie uitgezet.

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

Als een gebruiker tijdelijk overschakelt naar een tabblad waarvoor het zijvenster niet aanstaat, wordt het zijvenster verborgen. De advertentie wordt automatisch weer getoond als de gebruiker overschakelt naar een tabblad waarop de advertentie eerder was geopend.

Als de gebruiker naar een site gaat waar het zijvenster niet aanstaat, wordt het zijvenster gesloten en wordt de extensie niet getoond in het dropdownmenu van het zijvenster.

Bekijk het voorbeeld Tabbladspecifiek zijvenster voor een volledig voorbeeld.

Open het zijvenster door op het icoon in de werkbalk te klikken

Ontwikkelaars kunnen gebruikers toestaan het zijvenster te openen als ze op het icoon van de actiewerkbalk klikken met sidePanel.setPanelBehavior(). Definieer eerst de sleutel "action" in het manifest:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title&quot;: "Click to open panel"
  },
  ...
}

Voeg nu deze code toe aan het vorige voorbeeld:

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

Het zijvenster programmatisch openen bij gebruikersinteractie

In Chrome 116 introduceren we sidePanel.open(). Hiermee kunnen extensies het zijvenster openen via een gebruikersactivatie van de extensie, zoals klikken op het actie-icoon. Of een gebruikersinteractie op een extensiepagina of contentscript, zoals klikken op een knop. Bekijk de voorbeeldextensie Zijvenster openen voor een volledige demo.

De volgende code toont hoe je een algemeen zijvenster opent in het huidige venster als de gebruiker op een contextmenu klikt. Als je sidePanel.open() gebruikt, moet je de context kiezen waarin de app moet worden geopend. Gebruik windowId om een algemeen zijvenster te openen. Je kunt de tabId ook instellen om het zijvenster alleen op een specifiek tabblad te openen.

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

Overschakelen naar een ander deelvenster

Extensies kunnen sidepanel.getOptions() gebruiken om het huidige zijvenster op te halen. In het volgende voorbeeld wordt een welkomstzijvenster ingesteld op runtime.onInstalled(). Als de gebruiker naar een ander tabblad gaat, wordt het vervangen door het hoofdzijvenster.

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

Bekijk het voorbeeld Meerdere zijvensters voor de volledige code.

Gebruikerservaring van het zijvenster

Gebruikers zien eerst de ingebouwde zijvensters van Chrome. In elk zijvenster staat het icoon van de extensie in het menu van het zijvenster. Als er geen iconen zijn opgenomen, wordt er een tijdelijke aanduiding getoond met de eerste letter van de naam van de extensie.

Het zijvenster openen

Als je wilt dat gebruikers het zijvenster kunnen openen, gebruik je een actie-icoon in combinatie met sidePanel.setPanelBehavior(). U kunt ook een aanroep naar sidePanel.open() doen na een gebruikersinteractie, zoals:

Het zijvenster vastzetten

Icoon Vastzetten in de UI van het zijvenster.
Icoon Vastzetten in de UI van het zijvenster.

De werkbalk van het zijvenster toont een vastzeticoon als het zijvenster is geopend. Als je op het icoon klikt, wordt het actie-icoon van je extensie vastgezet. Als je op het actie-icoon klikt nadat je het hebt vastgezet, wordt de standaardactie voor je actie-icoon uitgevoerd. Het zijvenster wordt alleen geopend als dit expliciet is ingesteld.

Voorbeelden

Verken een van de volgende extensies voor meer demo's van de Side Panel API-extensies:

Typen

CloseOptions

Chrome 141 of hoger

Eigenschappen

  • tabId

    number optioneel

    Het tabblad waarin je het zijvenster wilt sluiten. Als er een tabbladspecifiek zijvenster is geopend op het aangegeven tabblad, wordt dit gesloten voor dat tabblad. Als alleen het algemene zijvenster is geopend, wordt de promise die wordt geretourneerd door de aanroep naar close() afgewezen met een foutmelding. Dit gedrag is gewijzigd in Chrome 145. Eerdere versies vallen terug op het sluiten van het algemene deelvenster. Je moet minimaal dit of windowId invoeren.

  • windowId

    number optioneel

    Het venster waarin je het zijvenster kunt sluiten. Als er een algemeen zijvenster is geopend in het aangegeven venster, wordt dit gesloten voor alle tabbladen in dat venster waar geen tabbladspecifiek venster actief is. Je moet minimaal dit of tabId invoeren.

GetPanelOptions

Eigenschappen

  • tabId

    number optioneel

    Als dit is opgegeven, worden de opties voor het zijvenster voor het opgegeven tabblad geretourneerd. Anders worden de standaardopties voor het zijvenster geretourneerd (gebruikt voor elk tabblad dat geen specifieke instellingen heeft).

OpenOptions

Chrome 116 of hoger

Eigenschappen

  • tabId

    number optioneel

    Het tabblad waarin het zijvenster moet worden geopend. Als het bijbehorende tabblad een tabbladspecifiek zijvenster heeft, wordt het venster alleen voor dat tabblad geopend. Als er geen tabbladspecifiek deelvenster is, wordt het algemene deelvenster geopend op het aangegeven tabblad en op andere tabbladen zonder een momenteel geopend tabbladspecifiek deelvenster. Dit overschrijft elk momenteel actief zijvenster (algemeen of tabbladspecifiek) op het bijbehorende tabblad. Je moet minimaal dit of windowId invoeren.

  • windowId

    number optioneel

    Het venster waarin het zijvenster moet worden geopend. Dit is alleen van toepassing als de extensie een algemeen (niet-tabbladspecifiek) zijvenster heeft of als tabId ook is ingevoerd. Dit overschrijft elk momenteel actief algemeen zijvenster dat de gebruiker in het betreffende venster heeft geopend. Je moet minimaal dit veld of tabId invullen.

PanelBehavior

Eigenschappen

  • openPanelOnActionClick

    booleaans optioneel

    Of de vermelding van de extensie in het zijvenster wordt getoond als je op het icoon van de extensie klikt. De standaard is onwaar.

PanelClosedInfo

Chrome 142 of hoger

Eigenschappen

  • pad

    tekenreeks

    Het pad van de lokale bron in het extensiepakket waarvan de content wordt getoond in het deelvenster.

  • tabId

    number optioneel

    De optionele ID van het tabblad waar het zijvenster is gesloten. Dit wordt alleen verstrekt als het deelvenster tabbladspecifiek is.

  • windowId

    getal

    De ID van het venster waarin het zijvenster is gesloten. Dit is beschikbaar voor zowel algemene als tabbladspecifieke deelvensters.

PanelLayout

Chrome 140+

Eigenschappen

PanelOpenedInfo

Chrome 141 of hoger

Eigenschappen

  • pad

    tekenreeks

    Het pad van de lokale bron in het extensiepakket waarvan de content wordt getoond in het deelvenster.

  • tabId

    number optioneel

    De optionele ID van het tabblad waar het zijvenster wordt geopend. Dit wordt alleen verstrekt als het deelvenster tabbladspecifiek is.

  • windowId

    getal

    De ID van het venster waarin het zijvenster wordt geopend. Dit is beschikbaar voor zowel algemene als tabbladspecifieke deelvensters.

PanelOptions

Eigenschappen

  • aangezet

    booleaans optioneel

    Of het zijvenster moet worden aangezet. Dit is optioneel. De standaardwaarde is true.

  • pad

    tekenreeks optioneel

    Het pad naar het html-bestand van het zijvenster dat je wilt gebruiken. Dit moet een lokale bron in het extensiepakket zijn.

  • tabId

    number optioneel

    Als dit is aangegeven, zijn de opties voor het zijvenster alleen van toepassing op het tabblad met deze ID. Als je deze opties weglaat, wordt het standaardgedrag ingesteld (gebruikt voor elk tabblad dat geen specifieke instellingen heeft). Opmerking: Als hetzelfde pad is ingesteld voor deze tabId en de standaard tabId, is het deelvenster voor deze tabId een andere instantie dan het deelvenster voor de standaard tabId.

Side

Chrome 140+

Definieert de mogelijke uitlijning voor het zijvenster in de browser-UI.

Enum

"left"

"right"

SidePanel

Eigenschappen

  • default_path

    tekenreeks

    Door de ontwikkelaar opgegeven pad voor weergave van het zijvenster.

Methoden

close()

Chrome 141 of hoger 
chrome.sidePanel.close(
  options: CloseOptions,
): Promise<void>

Sluit het zijvenster van de extensie. Dit is een no-op als het deelvenster al is gesloten.

Parameters

  • opties

    CloseOptions

    Hiermee wordt de context aangegeven waarin het zijvenster moet worden gesloten.

Retourzendingen

  • Promise<void>

    Retourneert een Promise die wordt opgelost als het zijvenster is gesloten.

getLayout()

Chrome 140+ 
chrome.sidePanel.getLayout(): Promise<PanelLayout>

Retourneert de huidige indeling van het zijvenster.

Retourzendingen

getOptions()

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

Retourneert de actieve deelvensterconfiguratie.

Parameters

  • Hiermee wordt de context aangegeven waarvoor de configuratie moet worden geretourneerd.

Retourzendingen

  • Promise<PanelOptions>

    Retourneert een Promise die wordt omgezet met de actieve deelvensterconfiguratie.

getPanelBehavior()

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

Retourneert het huidige gedrag van het zijvenster van de extensie.

Retourzendingen

  • Promise<PanelBehavior>

    Retourneert een Promise die wordt opgelost met het gedrag van het zijvenster van de extensie.

open()

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

Hiermee open je het zijvenster voor de extensie. Dit mag alleen worden aangeroepen als reactie op een gebruikersactie.

Parameters

  • opties

    OpenOptions

    Hiermee geef je de context aan waarin het zijvenster moet worden geopend.

Retourzendingen

  • Promise<void>

    Retourneert een Promise die wordt opgelost wanneer het zijvenster is geopend.

setOptions()

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

Hiermee stel je het zijvenster in.

Parameters

  • opties

    PanelOptions

    De configuratieopties die je op het deelvenster wilt toepassen.

Retourzendingen

  • Promise<void>

    Retourneert een Promise die wordt opgelost als de opties zijn ingesteld.

setPanelBehavior()

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

Hiermee stel je het gedrag van het zijvenster van de extensie in. Dit is een upsert-bewerking.

Parameters

  • van consumenten

    PanelBehavior

    Het nieuwe gedrag dat moet worden ingesteld.

Retourzendingen

  • Promise<void>

    Retourneert een Promise die wordt omgezet als het nieuwe gedrag is ingesteld.

Evenementen

onClosed

Chrome 142 of hoger 
chrome.sidePanel.onClosed.addListener(
  callback: function,
)

Wordt geactiveerd als het zijvenster van de extensie wordt gesloten.

Parameters

onOpened

Chrome 141 of hoger 
chrome.sidePanel.onOpened.addListener(
  callback: function,
)

Wordt geactiveerd als het zijvenster van de extensie wordt geopend.

Parameters