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é
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.
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.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 Plusieurs panneaux latéraux pour voir le code 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
Pour permettre aux utilisateurs d'ouvrir le panneau latéral, associez une icône d'action à sidePanel.setPanelBehavior()
. Vous pouvez également appeler sidePanel.open()
à la suite d'une interaction de l'utilisateur, par exemple:
- Un clic sur une action
- Un raccourci clavier
- Un menu contextuel
- Geste de l'utilisateur sur une page d'extension ou un script de contenu.
Épingler le panneau latéral
La barre d'outils du panneau latéral affiche une icône en forme de punaise lorsque le panneau latéral est ouvert. Cliquez dessus pour épingler l'icône d'action de votre extension. Si vous cliquez sur l'icône d'action une fois épinglée, l'action par défaut de cette icône sera appliquée et le panneau latéral ne s'ouvrira que s'il a été explicitement configuré.
Exemples
Pour voir d'autres démonstrations des extensions de l'API du panneau latéral, explorez l'une des extensions suivantes:
- Panneau latéral du dictionnaire :
- Panneau latéral global :
- Plusieurs panneaux latéraux :
- Ouvrez le panneau latéral.
- Panneau latéral spécifique au site :
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
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 outabId
.
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()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Renvoie la configuration de panneau active.
Paramètres
-
options
Spécifie le contexte pour lequel renvoyer la configuration.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(options: PanelOptions) => void
-
options
-
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()
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
-
des consommateurs
-
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()
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
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()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Configure le panneau latéral.
Paramètres
-
options
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()
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
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.