Descrizione
Utilizza l'API chrome.sidePanel per ospitare i contenuti nel riquadro laterale del browser insieme ai contenuti principali di una pagina web.
Autorizzazioni
sidePanelPer utilizzare l'API Side Panel, aggiungi l'autorizzazione "sidePanel" nel file manifest dell'estensione:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Disponibilità
Concetti e utilizzo
L'API Side Panel consente alle estensioni di mostrare la propria UI nel riquadro laterale, offrendo esperienze persistenti che completano il percorso di navigazione dell'utente.
Alcune funzionalità includono:
- Il riquadro laterale rimane aperto quando passi da una scheda all'altra (se impostato in questo modo).
- Può essere disponibile solo su siti web specifici.
- In quanto pagina di estensione, i riquadri laterali hanno accesso a tutte le API di Chrome.
- Nelle impostazioni di Chrome, gli utenti possono specificare su quale lato visualizzare il riquadro.
Casi d'uso
Le sezioni seguenti mostrano alcuni casi d'uso comuni per l'API Side Panel. Consulta Esempi di estensioni per esempi completi di estensioni.
Visualizza lo stesso riquadro laterale su ogni sito
Il riquadro laterale può essere impostato inizialmente dalla proprietà "default_path" nella chiave "side_panel" del manifest per visualizzare lo stesso riquadro laterale su ogni sito. Deve puntare a un percorso relativo all'interno della directory dell'estensione.
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>
Attiva un riquadro laterale su un sito specifico
Un'estensione può utilizzare sidepanel.setOptions() per attivare un riquadro laterale in una scheda specifica. Questo esempio utilizza browser.tabs.onUpdated() per rilevare eventuali aggiornamenti apportati alla scheda. Controlla se l'URL è www.google.com e attiva il riquadro laterale. In caso contrario, la disattiva.
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
});
}
});
Quando un utente passa temporaneamente a una scheda in cui il riquadro laterale non è attivo, il riquadro laterale viene nascosto. Verrà mostrato di nuovo automaticamente quando l'utente passa a una scheda in cui era aperto in precedenza.
Quando l'utente accede a un sito in cui il riquadro laterale non è attivo, il riquadro laterale si chiude e l'estensione non viene visualizzata nel menu a discesa del riquadro laterale.
Per un esempio completo, consulta l'esempio di riquadro laterale specifico per la scheda.
Apri il riquadro laterale facendo clic sull'icona della barra degli strumenti
Gli sviluppatori possono consentire agli utenti di aprire il riquadro laterale quando fanno clic sull'icona della barra degli strumenti delle azioni con sidePanel.setPanelBehavior(). Innanzitutto, dichiara la chiave "action" nel file manifest:
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
Ora aggiungi questo codice all'esempio precedente:
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));
...
Apri il riquadro laterale in modo programmatico in base all'interazione dell'utente
Chrome 116 introduce sidePanel.open(). Consente alle estensioni di aprire il riquadro laterale tramite un'attivazione dall'utente dell'estensione, ad esempio facendo clic sull'icona di azione. Oppure un'interazione dell'utente su una pagina di estensione o uno script di contenuti, ad esempio il clic su un pulsante. Per una demo completa, consulta l'estensione di esempio Apri riquadro laterale.
Il seguente codice mostra come aprire un riquadro laterale globale nella finestra corrente quando l'utente fa clic su un menu contestuale. Quando utilizzi sidePanel.open(), devi scegliere il contesto in cui deve aprirsi. Utilizza windowId per aprire un riquadro laterale globale. In alternativa, imposta tabId per aprire il riquadro laterale solo in una scheda specifica.
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 });
}
});
Passa a un altro pannello
Le estensioni possono utilizzare sidepanel.getOptions() per recuperare il riquadro laterale corrente. L'esempio seguente imposta un riquadro laterale di benvenuto su runtime.onInstalled(). Quando l'utente passa a un'altra scheda, viene sostituito con il riquadro laterale principale.
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 });
}
});
Per il codice completo, consulta l'esempio Più riquadri laterali.
Esperienza utente del riquadro laterale
Gli utenti vedranno prima i riquadri laterali integrati di Chrome. Ogni riquadro laterale mostra l'icona dell'estensione nel menu del riquadro laterale. Se non sono incluse icone, verrà visualizzata un'icona segnaposto con la prima lettera del nome dell'estensione.
Apri il riquadro laterale
Per consentire agli utenti di aprire il riquadro laterale, utilizza un'icona di azione in combinazione con sidePanel.setPanelBehavior(). In alternativa, effettua una chiamata a sidePanel.open() dopo un'interazione dell'utente, ad esempio:
- Un clic per l'azione
- Una scorciatoia da tastiera
- Un menu contestuale
- Un'attivazione dall'utente su una pagina di estensione o uno script di contenuti.
Fissa il riquadro laterale
Quando il riquadro laterale è aperto, la barra degli strumenti del riquadro laterale mostra un'icona a forma di puntina. Se fai clic sull'icona, l'icona di azione dell'estensione viene bloccata. Se fai clic sull'icona di azione una volta fissata, verrà eseguita l'azione predefinita per l'icona di azione e il riquadro laterale verrà aperto solo se è stato configurato esplicitamente.
Esempi
Per altre demo delle estensioni dell'API Side Panel, esplora una delle seguenti estensioni:
- Riquadro laterale del dizionario.
- Riquadro laterale globale.
- Più riquadri laterali.
- Apri il riquadro laterale.
- Riquadro laterale specifico del sito.
Tipi
CloseOptions
Proprietà
-
tabId
number optional
La scheda in cui chiudere il riquadro laterale. Se un riquadro laterale specifico della scheda è aperto nella scheda specificata, verrà chiuso per quella scheda. Se è aperto solo il riquadro laterale globale, la promise restituita dalla chiamata a
close()verrà rifiutata con un errore. Questo comportamento è stato modificato in Chrome 145, mentre le versioni precedenti tornavano alla chiusura del riquadro globale. È necessario fornire almeno questo owindowId. -
windowId
number optional
La finestra in cui chiudere il riquadro laterale. Se un riquadro laterale globale è aperto nella finestra specificata, verrà chiuso per tutte le schede di quella finestra in cui non è attivo un riquadro specifico della scheda. È necessario fornire almeno questo o
tabId.
GetPanelOptions
Proprietà
-
tabId
number optional
Se specificato, verranno restituite le opzioni del riquadro laterale per la scheda specificata. In caso contrario, restituisce le opzioni predefinite del riquadro laterale (utilizzate per qualsiasi scheda che non dispone di impostazioni specifiche).
OpenOptions
Proprietà
-
tabId
number optional
La scheda in cui aprire il riquadro laterale. Se la scheda corrispondente ha un riquadro laterale specifico, questo verrà aperto solo per quella scheda. Se non è presente un riquadro specifico per la scheda, il riquadro globale verrà aperto nella scheda specificata e in tutte le altre schede senza un riquadro specifico per la scheda attualmente aperto. In questo modo, verrà eseguito l'override di qualsiasi riquadro laterale attualmente attivo (globale o specifico della scheda) nella scheda corrispondente. È necessario fornire almeno questo o
windowId. -
windowId
number optional
La finestra in cui aprire il riquadro laterale. Questo vale solo se l'estensione ha un riquadro laterale globale (non specifico per la scheda) o se è specificato anche
tabId. In questo modo, verrà eseguito l'override di qualsiasi riquadro laterale globale attualmente attivo che l'utente ha aperto nella finestra specificata. È necessario fornire almeno questo otabId.
PanelBehavior
Proprietà
-
openPanelOnActionClick
boolean facoltativo
Indica se facendo clic sull'icona dell'estensione viene attivata/disattivata la visualizzazione della voce dell'estensione nel riquadro laterale. Il valore predefinito è false.
PanelClosedInfo
Proprietà
-
percorso
stringa
Il percorso della risorsa locale all'interno del pacchetto dell'estensione i cui contenuti vengono visualizzati nel riquadro.
-
tabId
number optional
L'ID facoltativo della scheda in cui è stato chiuso il riquadro laterale. Viene fornito solo quando il riquadro è specifico per la scheda.
-
windowId
numero
L'ID della finestra in cui è stato chiuso il riquadro laterale. Questa opzione è disponibile sia per i riquadri globali che per quelli specifici delle schede.
PanelLayout
Proprietà
-
side
PanelOpenedInfo
Proprietà
-
percorso
stringa
Il percorso della risorsa locale all'interno del pacchetto dell'estensione i cui contenuti vengono visualizzati nel riquadro.
-
tabId
number optional
L'ID facoltativo della scheda in cui viene aperto il riquadro laterale. Viene fornito solo quando il riquadro è specifico per la scheda.
-
windowId
numero
L'ID della finestra in cui viene aperto il riquadro laterale. Questa opzione è disponibile sia per i riquadri globali che per quelli specifici delle schede.
PanelOptions
Proprietà
-
attivato
boolean facoltativo
Indica se il riquadro laterale deve essere attivato. Questa opzione è facoltativa. Il valore predefinito è true.
-
percorso
stringa facoltativa
Il percorso del file HTML del riquadro laterale da utilizzare. Deve essere una risorsa locale all'interno del pacchetto dell'estensione.
-
tabId
number optional
Se specificate, le opzioni del riquadro laterale verranno applicate solo alla scheda con questo ID. Se omesse, queste opzioni impostano il comportamento predefinito (utilizzato per qualsiasi scheda che non dispone di impostazioni specifiche). Nota: se viene impostato lo stesso percorso per questo tabId e per il tabId predefinito, il riquadro per questo tabId sarà un'istanza diversa rispetto al riquadro per il tabId predefinito.
Side
Definisce il possibile allineamento del riquadro laterale nella UI del browser.
Enum
"left"
"right"
SidePanel
Proprietà
-
default_path
stringa
Percorso specificato dallo sviluppatore per la visualizzazione del riquadro laterale.
Metodi
close()
browser.sidePanel.close(
options: CloseOptions,
): Promise<void>
Chiude il riquadro laterale dell'estensione. Se il riquadro è già chiuso, non viene eseguita alcuna operazione.
Parametri
-
opzioni
Specifica il contesto in cui chiudere il riquadro laterale.
Resi
-
Promise<void>
Restituisce una Promise che si risolve quando il riquadro laterale viene chiuso.
getLayout()
browser.sidePanel.getLayout(): Promise<PanelLayout>
Restituisce il layout corrente del riquadro laterale.
Resi
-
Promise<PanelLayout>
Restituisce una promessa che si risolve con un
PanelLayout.
getOptions()
browser.sidePanel.getOptions(
options: GetPanelOptions,
): Promise<PanelOptions>
Restituisce la configurazione del panel attivo.
Parametri
-
opzioni
Specifica il contesto per cui restituire la configurazione.
Resi
-
Promise<PanelOptions>
Restituisce una Promise che si risolve con la configurazione del pannello attivo.
getPanelBehavior()
browser.sidePanel.getPanelBehavior(): Promise<PanelBehavior>
Restituisce il comportamento attuale del riquadro laterale dell'estensione.
Resi
-
Promise<PanelBehavior>
Restituisce una Promise che si risolve con il comportamento del riquadro laterale dell'estensione.
open()
browser.sidePanel.open(
options: OpenOptions,
): Promise<void>
Apre il riquadro laterale dell'estensione. Questo metodo può essere chiamato solo in risposta a un'azione dell'utente.
Parametri
-
opzioni
Specifica il contesto in cui aprire il riquadro laterale.
Resi
-
Promise<void>
Restituisce una Promise che si risolve quando il riquadro laterale è stato aperto.
setOptions()
browser.sidePanel.setOptions(
options: PanelOptions,
): Promise<void>
Configura il riquadro laterale.
Parametri
-
opzioni
Le opzioni di configurazione da applicare al riquadro.
Resi
-
Promise<void>
Restituisce una Promise che viene risolta quando le opzioni sono state impostate.
setPanelBehavior()
browser.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
): Promise<void>
Configura il comportamento del riquadro laterale dell'estensione. Questa è un'operazione di upsert.
Parametri
-
dei consumatori
Il nuovo comportamento da impostare.
Resi
-
Promise<void>
Restituisce una Promise che viene risolta quando viene impostato il nuovo comportamento.
Eventi
onClosed
browser.sidePanel.onClosed.addListener(
callback: function,
)
Viene attivato quando il riquadro laterale dell'estensione viene chiuso.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(info: PanelClosedInfo) => void
-
informazioni
-
onOpened
browser.sidePanel.onOpened.addListener(
callback: function,
)
Viene attivato quando viene aperto il riquadro laterale dell'estensione.
Parametri
-
callback
funzione
Il parametro
callbackha il seguente aspetto:(info: PanelOpenedInfo) => void
-
informazioni
-