browser.sidePanel

Description

Utilisez l'API chrome.sidePanel pour héberger du contenu dans le panneau latéral du navigateur, à côté du contenu principal d'une page Web.

Autorisations

sidePanel

Pour utiliser l'API Side Panel, ajoutez l'autorisation "sidePanel" dans le fichier manifest de l'extension :

manifest.json:

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

Disponibilité

Chrome 114+ browser.* depuis Chrome 148 MV3+

Concepts et utilisation

L'API Side Panel permet aux extensions d'afficher leur propre UI dans le panneau latéral, ce qui permet d'offrir des expériences persistantes qui complètent le parcours de navigation de l'utilisateur.

Menu déroulant du panneau latéral
UI du panneau latéral du navigateur Chrome.

Voici quelques-unes de ces fonctionnalités :

  • Le panneau latéral reste ouvert lorsque vous passez d'un onglet à l'autre (si vous l'avez configuré ainsi).
  • Il peut n'être disponible que sur certains sites Web.
  • En tant que page d'extension, les panneaux latéraux ont accès à toutes les API Chrome.
  • Dans les paramètres de Chrome, les utilisateurs peuvent spécifier de quel côté le panneau doit s'afficher.

Cas d'utilisation

Les sections suivantes présentent des cas d'utilisation courants de l'API Side Panel. Consultez la section Exemples d'extensions pour obtenir des exemples complets d'extensions.

Afficher le même panneau latéral sur tous les sites

Le panneau latéral peut être défini initialement à partir de la propriété "default_path" dans la clé "side_panel" du fichier manifeste pour afficher le même panneau latéral sur chaque site. Il doit pointer vers un chemin relatif dans le répertoire de l'extension.

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>

Activer un panneau latéral sur un site spécifique

Une extension peut utiliser sidepanel.setOptions() pour activer un panneau latéral sur un onglet spécifique. Cet exemple utilise browser.tabs.onUpdated() pour écouter les modifications apportées à l'onglet. Elle vérifie si l'URL est www.google.com et active le panneau latéral. Sinon, il la désactive.

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

Lorsqu'un utilisateur passe temporairement à un onglet où le panneau latéral n'est pas activé, le panneau latéral est masqué. Il s'affichera à nouveau automatiquement lorsque l'utilisateur passera à un onglet où il était précédemment ouvert.

Lorsque l'utilisateur accède à un site sur lequel le panneau latéral n'est pas activé, le panneau latéral se ferme et l'extension ne s'affiche pas dans le menu déroulant du panneau latéral.

Pour obtenir un exemple complet, consultez l'exemple Panneau latéral spécifique à un onglet.

Ouvrez le panneau latéral en cliquant sur l'icône de la barre d'outils.

Les développeurs peuvent permettre aux utilisateurs d'ouvrir le panneau latéral lorsqu'ils cliquent sur l'icône de la barre d'outils d'action avec sidePanel.setPanelBehavior(). Tout d'abord, déclarez la clé "action" dans le fichier manifeste :

manifest.json:

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

Ajoutez maintenant ce code à l'exemple précédent :

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

Ouvrir le panneau latéral de manière programmatique lors d'une interaction de l'utilisateur

Chrome 116 introduit sidePanel.open(). Elle permet aux extensions d'ouvrir le panneau latéral via un geste de l'utilisateur, comme un clic sur l'icône d'action. ou une interaction de l'utilisateur sur une page d'extension ou un script de contenu, comme un clic sur un bouton. Pour une démonstration complète, consultez l'exemple d'extension Open Side Panel.

Le code suivant montre comment ouvrir un panneau latéral global dans la fenêtre actuelle lorsque l'utilisateur clique sur un menu contextuel. Lorsque vous utilisez sidePanel.open(), vous devez choisir le contexte dans lequel il doit s'ouvrir. Utilisez windowId pour ouvrir un panneau latéral global. Vous pouvez également définir tabId pour n'ouvrir le panneau latéral que sur un onglet spécifique.

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

Passer à un autre panneau

Les extensions peuvent utiliser sidepanel.getOptions() pour récupérer le panneau latéral actuel. L'exemple suivant définit un panneau latéral de bienvenue sur runtime.onInstalled(). Ensuite, lorsque l'utilisateur accède à un autre onglet, il le remplace par le panneau latéral principal.

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

Pour obtenir le code complet, consultez l'exemple Plusieurs panneaux latéraux.

Expérience utilisateur du panneau latéral

Les utilisateurs verront d'abord les panneaux latéraux intégrés de Chrome. Chaque panneau latéral affiche l'icône de l'extension dans le menu du panneau latéral. Si aucune icône n'est incluse, une icône d'espace réservé s'affiche avec la première lettre du nom de l'extension.

Ouvrir le panneau latéral

Pour permettre aux utilisateurs d'ouvrir le panneau latéral, utilisez une icône d'action en combinaison avec sidePanel.setPanelBehavior(). Vous pouvez également appeler sidePanel.open() après une interaction de l'utilisateur, par exemple :

Épingler le panneau latéral

Icône en forme de punaise dans l'UI du panneau latéral.
Icône d'épingle dans l'interface utilisateur du panneau latéral.

La barre d'outils du panneau latéral affiche une icône d'épingle lorsque le panneau latéral est ouvert. Cliquez sur l'icône pour épingler l'icône d'action de votre extension. Si vous cliquez sur l'icône d'action une fois qu'elle est épinglée, l'action par défaut de votre icône d'action est exécutée et le panneau latéral ne s'ouvre que si cela a été explicitement configuré.

Exemples

Pour découvrir d'autres démonstrations d'extensions de l'API Side Panel, explorez l'une des extensions suivantes :

Types

CloseOptions

Chrome 141+ browser.* depuis Chrome 148

Propriétés

  • tabId

    number facultatif

    Onglet dans lequel fermer le panneau latéral. Si un panneau latéral spécifique à un onglet est ouvert dans l'onglet spécifié, il sera fermé pour cet onglet. Si seul le panneau latéral global est ouvert, la promesse renvoyée par l'appel à close() sera rejetée avec une erreur. Ce comportement a été modifié dans Chrome 145. Les versions antérieures ferment le panneau global. Vous devez fournir au moins l'un de ces champs ou windowId.

  • windowId

    number facultatif

    Fenêtre dans laquelle fermer le panneau latéral. Si un panneau latéral global est ouvert dans la fenêtre spécifiée, il sera fermé pour tous les onglets de cette fenêtre où aucun panneau spécifique à l'onglet n'est actif. Vous devez fournir au moins l'un de ces champs ou tabId.

GetPanelOptions

Propriétés

  • tabId

    number facultatif

    Si elle est spécifiée, les options du panneau latéral pour l'onglet donné sont renvoyées. Sinon, renvoie les options du panneau latéral par défaut (utilisées pour tous les onglets qui n'ont pas de paramètres spécifiques).

OpenOptions

Chrome 116+ browser.* depuis Chrome 148

Propriétés

  • tabId

    number facultatif

    Onglet dans lequel ouvrir le panneau latéral. Si l'onglet correspondant dispose d'un panneau latéral spécifique, celui-ci ne sera ouvert que pour cet onglet. S'il n'y a pas de panneau spécifique à l'onglet, le panneau global s'ouvre dans l'onglet spécifié et dans tous les autres onglets sans panneau spécifique à l'onglet actuellement ouvert. Cela remplacera tout panneau latéral actuellement actif (global ou spécifique à un onglet) dans l'onglet correspondant. Vous devez fournir au moins l'un de ces champs ou windowId.

  • windowId

    number facultatif

    Fenêtre dans laquelle ouvrir le panneau latéral. Cela ne s'applique que si l'extension dispose d'un panneau latéral global (non spécifique à un onglet) ou si tabId est également spécifié. Cela remplacera tout panneau latéral global actuellement actif que l'utilisateur a ouvert dans la fenêtre donnée. Vous devez fournir au moins l'un de ces champs ou tabId.

PanelBehavior

Propriétés

  • openPanelOnActionClick

    boolean facultatif

    Indique si le fait de cliquer sur l'icône de l'extension permet d'afficher ou non l'entrée de l'extension dans le panneau latéral. Valeur par défaut : "false".

PanelClosedInfo

Chrome 142+ browser.* depuis Chrome 148

Propriétés

  • chemin d'accès

    chaîne

    Chemin d'accès de la ressource locale dans le package d'extension dont le contenu est affiché dans le panneau.

  • tabId

    number facultatif

    ID facultatif de l'onglet dans lequel le panneau latéral a été fermé. Cette option n'est fournie que lorsque le panneau est spécifique à un onglet.

  • windowId

    nombre

    ID de la fenêtre dans laquelle le panneau latéral a été fermé. Cette option est disponible pour les panneaux globaux et spécifiques à un onglet.

PanelLayout

Chrome 140+ browser.* depuis Chrome 148

Propriétés

PanelOpenedInfo

Chrome 141+ browser.* depuis Chrome 148

Propriétés

  • chemin d'accès

    chaîne

    Chemin d'accès de la ressource locale dans le package d'extension dont le contenu est affiché dans le panneau.

  • tabId

    number facultatif

    ID facultatif de l'onglet dans lequel le panneau latéral est ouvert. Cette option n'est fournie que lorsque le panneau est spécifique à un onglet.

  • windowId

    nombre

    ID de la fenêtre dans laquelle le panneau latéral est ouvert. Cette option est disponible pour les panneaux globaux et spécifiques à un onglet.

PanelOptions

Propriétés

  • activé

    boolean facultatif

    Indique si le panneau latéral doit être activé. Ceci est facultatif. La valeur par défaut est "true".

  • chemin d'accès

    chaîne facultatif

    Chemin d'accès au fichier HTML du panneau latéral à utiliser. Il doit s'agir d'une ressource locale dans le package d'extension.

  • tabId

    number facultatif

    Si elles sont spécifiées, les options du panneau latéral ne s'appliqueront qu'à l'onglet associé à cet ID. Si elles sont omises, ces options définissent le comportement par défaut (utilisé pour tout onglet ne disposant pas de paramètres spécifiques). Remarque : Si le même chemin est défini pour ce tabId et le tabId par défaut, le panneau de ce tabId sera une instance différente de celle du panneau du tabId par défaut.

Side

Chrome 140+ browser.* depuis Chrome 148

Définit l'alignement possible du panneau latéral dans l'interface utilisateur du navigateur.

Énumération

"left"

"right"

SidePanel

Propriétés

  • default_path

    chaîne

    Chemin spécifié par le développeur pour l'affichage du panneau latéral.

Méthodes

close()

Chrome 141+ browser.* depuis Chrome 148 
browser.sidePanel.close(
  options: CloseOptions,
): Promise<void>

Ferme le panneau latéral de l'extension. Cette opération n'a aucun effet si le panneau est déjà fermé.

Paramètres

  • options

    CloseOptions

    Spécifie le contexte dans lequel fermer le panneau latéral.

Renvoie

  • Promise<void>

    Renvoie une promesse qui se résout lorsque le panneau latéral est fermé.

getLayout()

Chrome 140+ browser.* depuis Chrome 148 
browser.sidePanel.getLayout(): Promise<PanelLayout>

Renvoie la mise en page actuelle du panneau latéral.

Renvoie

getOptions()

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

Renvoie la configuration du panneau actif.

Paramètres

  • options

    GetPanelOptions

    Spécifie le contexte pour lequel renvoyer la configuration.

Renvoie

  • Promise<PanelOptions>

    Renvoie une promesse qui se résout avec la configuration du panneau actif.

getPanelBehavior()

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

Renvoie le comportement actuel du panneau latéral de l'extension.

Renvoie

  • Promise<PanelBehavior>

    Renvoie une promesse qui se résout avec le comportement du panneau latéral de l'extension.

open()

Chrome 116+ browser.* depuis Chrome 148 
browser.sidePanel.open(
  options: OpenOptions,
): Promise<void>

Ouvre le panneau latéral de l'extension. Cette méthode ne peut être appelée qu'en réponse à une action de l'utilisateur.

Paramètres

  • options

    OpenOptions

    Spécifie le contexte dans lequel ouvrir le panneau latéral.

Renvoie

  • Promise<void>

    Renvoie une promesse qui se résout lorsque le panneau latéral est ouvert.

setOptions()

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

Configure le panneau latéral.

Paramètres

  • options

    PanelOptions

    Options de configuration à appliquer au panneau.

Renvoie

  • Promise<void>

    Renvoie une promesse qui se résout lorsque les options ont été définies.

setPanelBehavior()

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

Configure le comportement du panneau latéral de l'extension. Il s'agit d'une opération d'upsert.

Paramètres

  • des consommateurs

    PanelBehavior

    Nouveau comportement à définir.

Renvoie

  • Promise<void>

    Renvoie une promesse qui se résout lorsque le nouveau comportement a été défini.

Événements

onClosed

Chrome 142+ browser.* depuis Chrome 148 
browser.sidePanel.onClosed.addListener(
  callback: function,
)

Se déclenche lorsque le panneau latéral de l'extension est fermé.

Paramètres

onOpened

Chrome 141+ browser.* depuis Chrome 148 
browser.sidePanel.onOpened.addListener(
  callback: function,
)

Se déclenche lorsque le panneau latéral de l'extension est ouvert.

Paramètres