chrome.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 manifeste de l'extension :

manifest.json:

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

Disponibilité

Chrome 114 et versions ultérieures MV3 et versions ultérieures

Concepts et utilisation

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

Menu déroulant du panneau latéral
Interface utilisateur du panneau latéral du navigateur Chrome.

Voici quelques exemples de fonctionnalités :

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

Cas d'utilisation

Les sections suivantes présentent quelques cas d'utilisation courants de l'API Side Panel. Pour obtenir des exemples complets d'extensions, consultez Exemples 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 s'agir d'un chemin d'accès 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 dans un onglet spécifique. Cet exemple utilise chrome.tabs.onUpdated() pour écouter les mises à jour apportées à l'onglet. Il vérifie si l'URL est www.google.com et active le panneau latéral. Sinon, il le désactive.

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

Lorsqu'un utilisateur bascule temporairement vers un onglet où le panneau latéral n'est pas activé, celui-ci est masqué. Il s'affichera automatiquement à nouveau lorsque l'utilisateur passera à un onglet dans lequel 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 autoriser les utilisateurs à ouvrir le panneau latéral lorsqu'ils cliquent sur l'icône de la barre 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
chrome.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 par le biais d'un geste de l'utilisateur, par exemple en cliquant sur l'icône d'action. ou une interaction 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'extension exemple 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 ouvrir le panneau latéral uniquement dans un onglet spécifique.

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

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 d'accueil sur runtime.onInstalled(). Ensuite, lorsque l'utilisateur accède à un autre onglet, il est remplacé par le panneau latéral principal.

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

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 de substitution s'affichera avec la première lettre du nom de l'extension.

Ouvrir le panneau latéral

Pour autoriser les utilisateurs à 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&#39;interface utilisateur du panneau latéral.
Icône en forme d'épingle dans l'UI du panneau latéral.

La barre d'outils du panneau latéral affiche une icône en forme de punaise lorsque votre 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 l'icône s'exécute. 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 les extensions suivantes :

Types

CloseOptions

En attente

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. Au moins l'un des champs windowId ou celui-ci doit être défini.

  • 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 à un onglet n'est actif. Au moins l'un des champs tabId ou celui-ci doit être défini.

GetPanelOptions

Propriétés

  • tabId

    number facultatif

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

OpenOptions

Chrome 116 et versions ultérieures

Propriétés

  • tabId

    number facultatif

    Onglet dans lequel ouvrir le panneau latéral. Si l'onglet correspondant comporte 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 sera ouvert dans l'onglet spécifié et dans tous les autres onglets sans panneau spécifique actuellement ouvert. Cela remplacera tout panneau latéral actuellement actif (global ou spécifique à un onglet) dans l'onglet correspondant. Au moins l'un des champs windowId ou celui-ci doit être défini.

  • 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 et ouvert par l'utilisateur dans la fenêtre donnée. Au moins l'un des champs tabId ou celui-ci doit être défini.

PanelBehavior

Propriétés

  • openPanelOnActionClick

    booléen facultatif

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

PanelLayout

En attente

Propriétés

PanelOptions

Propriétés

  • activé

    booléen 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 facultative

    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 cette option est spécifiée, les options du panneau latéral ne s'appliqueront qu'à l'onglet portant cet ID. Si vous ne renseignez pas ces options, le comportement par défaut est défini (il est utilisé pour tous les onglets qui n'ont pas de paramètres spécifiques). Remarque : Si le même chemin est défini pour cet ID d'onglet et l'ID d'onglet par défaut, le panneau correspondant à cet ID d'onglet sera une instance différente de celle du panneau correspondant à l'ID d'onglet par défaut.

Side

En attente

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

getLayout()

En attente
chrome.sidePanel.getLayout(): Promise<PanelLayout>

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

Renvoie

getOptions()

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

getPanelBehavior()

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

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

Renvoie

open()

Chrome 116 et versions ultérieures 
chrome.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

    Indique le contexte dans lequel ouvrir le panneau latéral.

Renvoie

  • Promise<void>

setOptions()

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

Configure le panneau latéral.

Paramètres

  • options

    PanelOptions

    Options de configuration à appliquer au panneau.

Renvoie

  • Promise<void>

setPanelBehavior()

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