chrome.sidePanel

Descrizione

Utilizza l'API chrome.sidePanel per ospitare contenuti nel riquadro laterale del browser insieme ai contenuti principali di una pagina web.

Autorizzazioni

sidePanel

Per utilizzare l'API Side Panel, aggiungi l'autorizzazione "sidePanel" nel file manifest dell'estensione:

manifest.json:

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

Disponibilità

Chrome 114+ MV3+

Concetti e utilizzo

L'API Side Panel consente alle estensioni di visualizzare la propria UI nel riquadro laterale, offrendo esperienze persistenti che completano il percorso di navigazione dell'utente.

Menu a discesa del riquadro laterale
Interfaccia utente del riquadro laterale del browser Chrome.

Alcune funzionalità includono:

  • Il riquadro laterale rimane aperto quando si passa 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 Chrome.
  • Nelle impostazioni di Chrome, gli utenti possono specificare su quale lato deve essere visualizzato 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.

Visualizzare 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>

Attivare 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 chrome.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';

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

Quando un utente passa temporaneamente a una scheda in cui il riquadro laterale non è attivato, quest'ultimo viene nascosto. Verrà visualizzato di nuovo automaticamente quando l'utente passa a una scheda in cui era aperto in precedenza.

Quando l'utente passa a un sito in cui il pannello laterale non è attivato, il pannello laterale si chiude e l'estensione non viene visualizzata nel menu a discesa del pannello laterale.

Per un esempio completo, consulta l'esempio 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 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
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));
...

Aprire 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 gesto dell'utente dell'estensione, ad esempio fare clic sull'icona dell'azione. Oppure un'interazione dell'utente su una pagina di estensione o uno script dei contenuti, ad esempio un 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:

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

Passare a un altro riquadro

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, questa viene sostituita dal riquadro laterale principale.

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

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 al numero sidePanel.open() dopo un'interazione dell'utente, ad esempio:

Bloccare il riquadro laterale

Icona del segnaposto nell&#39;interfaccia utente del riquadro laterale.
Icona a forma di puntina nell'interfaccia utente del riquadro laterale.

La barra degli strumenti del riquadro laterale mostra un'icona a forma di puntina quando il riquadro laterale è aperto. Se fai clic sull'icona, viene bloccata l'icona dell'azione dell'estensione. Se fai clic sull'icona dell'azione dopo averla bloccata, verrà eseguita l'azione predefinita per l'icona dell'azione e il riquadro laterale verrà aperto solo se è stato configurato esplicitamente.

Esempi

Per altre demo di estensioni dell'API Side Panel, esplora una delle seguenti estensioni:

Tipi

GetPanelOptions

Proprietà

  • tabId

    number (facoltativo)

    Se specificate, 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

Chrome 116+

Proprietà

  • tabId

    number (facoltativo)

    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à sovrascritto qualsiasi riquadro laterale attualmente attivo (globale o specifico per la scheda) nella scheda corrispondente. È necessario specificare almeno uno di questi valori o windowId.

  • windowId

    number (facoltativo)

    La finestra in cui aprire il riquadro laterale. Ciò è applicabile solo se l'estensione ha un riquadro laterale globale (non specifico per la scheda) o se è specificato anche tabId. In questo modo, il riquadro laterale globale attualmente attivo aperto dall'utente nella finestra specificata verrà sostituito. È necessario specificare almeno uno di questi valori o tabId.

PanelBehavior

Proprietà

  • openPanelOnActionClick

    booleano facoltativo

    Se facendo clic sull'icona dell'estensione viene attivata o disattivata la visualizzazione della voce dell'estensione nel riquadro laterale. Il valore predefinito è false.

PanelLayout

In attesa

Proprietà

PanelOptions

Proprietà

  • attivato

    booleano 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 di estensione.

  • tabId

    number (facoltativo)

    Se specificate, le opzioni del riquadro laterale verranno applicate solo alla scheda con questo ID. Se omessi, questi parametri impostano il comportamento predefinito (utilizzato per qualsiasi scheda senza impostazioni specifiche). Nota: se lo stesso percorso è impostato per questo tabId e per il tabId predefinito, il riquadro per questo tabId sarà un'istanza diversa da quella per il tabId predefinito.

Side

In attesa

Definisce l'allineamento possibile per il riquadro laterale nell'interfaccia utente del browser.

Enum

"sinistra"

"destra"

SidePanel

Proprietà

  • default_path

    stringa

    Percorso specificato dallo sviluppatore per la visualizzazione del riquadro laterale.

Metodi

getLayout()

Promessa In attesa
chrome.sidePanel.getLayout(
  callback?: function,
)

Restituisce il layout corrente del riquadro laterale.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (layout: PanelLayout) => void

Resi

  • Promise<PanelLayout>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getOptions()

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

Restituisce la configurazione del pannello attivo.

Parametri

  • opzioni

    GetPanelOptions

    Specifica il contesto per cui restituire la configurazione.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (options: PanelOptions) => void

Resi

  • Promise<PanelOptions>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getPanelBehavior()

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

Restituisce il comportamento attuale del riquadro laterale dell'estensione.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (behavior: PanelBehavior) => void

Resi

  • Promise<PanelBehavior>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

open()

Promessa Chrome 116+ 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Apre il riquadro laterale dell'estensione. Può essere chiamato solo in risposta a un'azione dell'utente.

Parametri

  • opzioni

    OpenOptions

    Specifica il contesto in cui aprire il riquadro laterale.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

setOptions()

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

Configura il riquadro laterale.

Parametri

  • opzioni

    PanelOptions

    Le opzioni di configurazione da applicare al pannello.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

setPanelBehavior()

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

Configura il comportamento del riquadro laterale dell'estensione. Si tratta di un'operazione di upsert.

Parametri

  • dei consumatori

    PanelBehavior

    Il nuovo comportamento da impostare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma le callback vengono fornite per compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.