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 manifest de l'extension:

manifest.json:

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

Garantie de 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 d'offrir 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-unes des fonctionnalités disponibles:

  • Le panneau latéral reste ouvert lors de la navigation entre les onglets (s'il est configuré de cette manière).
  • Elle ne peut être disponible que sur des sites Web spécifiques.
  • 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 le côté du panneau qui doit s'afficher.

Cas d'utilisation

Les sections suivantes illustrent certains cas d'utilisation courants de l'API Side Panel. Consultez des exemples d'extensions pour voir des exemples complets.

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" de la clé "side_panel" du fichier manifeste pour afficher le même panneau latéral sur tous les sites. Elle doit renvoyer vers un chemin d'accès relatif dans le répertoire d'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 modifications apportées à l'onglet. Il vérifie si l'URL est www.google.com et active le panneau latéral. Dans le cas contraire, elle est désactivée.

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 passe temporairement à un onglet où le panneau latéral n'est pas activé, celui-ci est masqué. Elle s'affichera automatiquement lorsque l'utilisateur accédera à un onglet dans lequel il était ouvert.

Lorsque l'utilisateur accède à un site où le panneau latéral n'est pas activé, celui-ci se ferme et l'extension n'apparaît plus dans le menu déroulant.

Pour obtenir un exemple complet, consultez l'exemple de panneau latéral spécifique aux onglets.

Ouvrir 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'outils d'action avec sidePanel.setPanelBehavior(). Commencez par déclarer 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 par programmation lors d'une interaction de l'utilisateur

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

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 configurer l'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 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';

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

Consultez la section Plusieurs panneaux latéraux pour un exemple complet.

Expérience utilisateur dans le 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

Accéder au menu du panneau latéral
Les utilisateurs peuvent accéder aux panneaux latéraux disponibles dans le menu du panneau latéral. Ils peuvent ensuite choisir une extension dans le menu déroulant.
Menu déroulant du panneau latéral
UI du panneau latéral du navigateur Chrome
Ouvrir d'un geste de l'utilisateur

Vous pouvez ouvrir le panneau latéral lors d'interactions utilisateur à l'aide de sidePanel.open() et sidePanel.setPanelBehavior(), par exemple:

Exemples

Pour voir d'autres démonstrations des extensions de l'API du panneau latéral, explorez l'une des extensions suivantes:

Types

GetPanelOptions

Propriétés

  • tabId

    numéro facultatif

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

OpenOptions

Chrome 116 et versions ultérieures

Propriétés

  • tabId

    numéro facultatif

    Onglet dans lequel ouvrir le panneau latéral. Si l'onglet correspondant possède un panneau latéral qui lui est propre, il ne s'ouvrira que pour cet onglet. S'il n'y a pas de panneau spécifique à un onglet, le panneau global s'ouvrira dans l'onglet spécifié et dans tous les autres onglets n'en comportant pas. Cette action remplace tout panneau latéral actuellement actif (global ou spécifique à un onglet) dans l'onglet correspondant. Vous devez fournir au moins l'une de ces valeurs ou windowId.

  • windowId

    numéro facultatif

    Fenêtre dans laquelle ouvrir le panneau latéral. Cela ne s'applique que si l'extension comporte 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'une de ces valeurs ou tabId.

PanelBehavior

Propriétés

  • openPanelOnActionClick

    Booléen facultatif

    Ce paramètre détermine si le fait de cliquer sur l'icône de l'extension affiche ou non l'entrée de l'extension dans le panneau latéral. Valeur par défaut : "false".

PanelOptions

Propriétés

  • activé

    Booléen facultatif

    Activer ou non le panneau latéral. Ceci est facultatif. La valeur par défaut est "true".

  • chemin d'accès

    string 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

    numéro facultatif

    Si cette option est spécifiée, 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 tous les onglets qui ne comportent pas de paramètres spécifiques). Remarque: si le même chemin d'accès est défini pour cet tabId et pour l'ID tabId par défaut, le panneau correspondant à cet tabId sera une instance différente de celle de tabId par défaut.

SidePanel

Propriétés

  • default_path

    chaîne

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

Méthodes

getOptions()

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

Renvoie la configuration de panneau active.

Paramètres

  • options

    GetPanelOptions

    Spécifie le contexte pour lequel renvoyer la configuration.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    (options: PanelOptions)=>void

Renvoie

  • Promise<PanelOptions>

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getPanelBehavior()

Promesse 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

Paramètres

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    (behavior: PanelBehavior)=>void

Renvoie

  • Promise<PanelBehavior>

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

open()

Promettre Chrome 116 et versions ultérieures 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

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.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    ()=>void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

setOptions()

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

Configure le panneau latéral.

Paramètres

  • options

    PanelOptions

    Options de configuration à appliquer au panneau.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    ()=>void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

setPanelBehavior()

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

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

Paramètres

  • des consommateurs

    PanelBehavior

    Nouveau comportement à définir.

  • rappel

    fonction facultative

    Le paramètre callback se présente comme suit : 

    ()=>void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.