chrome.sidePanel

Description

Utilisez l'API chrome.sidePanel pour héberger le contenu du panneau latéral du navigateur avec le 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 ou version ultérieure MV3+

Concepts et utilisation

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

<ph type="x-smartling-placeholder">
</ph> Menu déroulant du panneau latéral <ph type="x-smartling-placeholder">
</ph> UI 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é).
  • Il ne peut être disponible que sur certains sites Web.
  • En tant qu'extension, les panneaux latéraux permettent d'accéder à 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. Consultez la section Exemples d'extensions pour obtenir des exemples complets.

Afficher le même panneau latéral sur chaque site

Le panneau latéral peut être initialement défini à 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 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 modifications apportées à l'onglet. Il 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';

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 pour lequel le panneau latéral n'est pas activé, celui-ci est masqué. Elle s'affichera de nouveau automatiquement lorsque l'utilisateur changera d'onglet.

Lorsque l'utilisateur accède à un site sur lequel le panneau latéral n'est pas activé, celui-ci 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 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 sidePanel.setPanelBehavior() de la barre d'outils d'actions. 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 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 sur un script de contenu, comme un clic sur un bouton. Pour voir une démonstration complète, consultez l'exemple d'extension 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 général. Vous pouvez également configurer tabId pour qu'il n'ouvre le panneau latéral que 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 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 });
  }
});

Consultez l'exemple Panneaux latéraux multiples pour obtenir le code complet.

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é apparaît 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 avec sidePanel.setPanelBehavior(). Vous pouvez également appeler sidePanel.open() après une interaction utilisateur, par exemple:

Épingler le panneau latéral

<ph type="x-smartling-placeholder">
</ph> Icône Épingler dans le panneau latéral de l&#39;interface utilisateur <ph type="x-smartling-placeholder">
</ph> Icône Épingler dans le panneau latéral de l'interface utilisateur

La barre d'outils du panneau latéral affiche une icône en forme de punaise lorsque le panneau latéral est ouvert. Cliquez sur l'icône pour épingler l'icône d'action de votre extension. Cliquer sur l'icône d'action une fois épinglée exécute l'action par défaut pour votre icône d'action et n'effectue ouvrir le panneau latéral s'il a été explicitement configuré.

Exemples

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

Types

GetPanelOptions

Propriétés

  • tabId

    numéro facultatif

    Si une valeur 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 ne possèdent 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 comporte un panneau latéral spécifique, celui-ci ne s'ouvrira que pour cet onglet. S'il n'existe pas de panneau spécifique à un onglet, le panneau global s'ouvre dans l'onglet spécifié et dans tous les autres onglets pour lesquels aucun panneau spécifique n'est 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

    numéro 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 actif que l'utilisateur a ouvert dans la fenêtre donnée. Vous devez fournir au moins l'un des champs suivants ou tabId.

PanelBehavior

Propriétés

  • openPanelOnActionClick

    Booléen facultatif

    Permet d'activer ou de désactiver l'affichage de 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

    chaîne facultatif

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

  • tabId

    numéro facultatif

    Si cet ID est spécifié, les options du panneau latéral ne s'appliqueront qu'à l'onglet correspondant. Si ces options sont omises, elles définissent le comportement par défaut (utilisées pour tout onglet ne disposant pas de paramètres spécifiques). Remarque: Si le même chemin d'accès 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 celui du panneau de l'ID d'onglet 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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.sidePanel.getOptions(
  options: GetPanelOptions,
  callback?: function,
)

Affiche la configuration du panneau actif.

Paramètres

  • options

    GetPanelOptions

    Spécifie le contexte pour lequel renvoyer la configuration.

  • rappel

    function facultatif

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

    (options: PanelOptions) => void

Renvoie

  • Promise&lt;PanelOptions&gt;

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

getPanelBehavior()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.sidePanel.getPanelBehavior(
  callback?: function,
)

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

Paramètres

  • rappel

    function facultatif

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

    (behavior: PanelBehavior) => void

Renvoie

  • Promise&lt;PanelBehavior&gt;

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

open()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 116 ou version ultérieure 
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

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

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

setOptions()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.sidePanel.setOptions(
  options: PanelOptions,
  callback?: function,
)

Configure le panneau latéral.

Paramètres

  • options

    PanelOptions

    Options de configuration à appliquer au panneau.

  • rappel

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

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

setPanelBehavior()

<ph type="x-smartling-placeholder"></ph> 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

    function facultatif

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

    () => void

Renvoie

  • Promesse<void>

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