chrome.sidePanel

Descrizione

Usa l'API chrome.sidePanel per ospitare i 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 e versioni successive MV3 o versioni successive

Concetti e utilizzo

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

Menu a discesa del riquadro laterale
UI del riquadro laterale del browser Chrome.

Alcune funzionalità includono:

  • Il riquadro laterale rimane aperto durante la navigazione tra le schede (se impostato in questo modo).
  • Può essere disponibile solo su siti web specifici.
  • Come 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 seguenti sezioni mostrano alcuni casi d'uso comuni per l'API Side Panel. Per esempi completi di estensioni, consulta Esempi di estensioni.

Mostrare lo stesso riquadro laterale su ogni sito

Il riquadro laterale può essere inizialmente impostato dalla proprietà "default_path" nella chiave "side_panel" del manifest in modo che venga visualizzato lo stesso riquadro laterale su ogni sito. Dovrebbe 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. In questo esempio viene utilizzato chrome.tabs.onUpdated() per rimanere in ascolto di eventuali aggiornamenti apportati alla scheda. Controlla se l'URL è www.google.com e attiva il riquadro laterale. In caso contrario, la funzionalità verrà disattivata.

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. Viene mostrata di nuovo automaticamente quando l'utente passa a una scheda aperta in precedenza.

Quando l'utente accede a un sito in cui il riquadro laterale non è attivato, questo viene chiuso e l'estensione non viene visualizzata nel menu a discesa del riquadro laterale.

Per un esempio completo, vedi l'esempio di riquadro laterale specifico per le schede.

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

Apri in modo programmatico il riquadro laterale durante l'interazione dell'utente

In Chrome 116 viene introdotto sidePanel.open(). Consente alle estensioni di aprire il riquadro laterale tramite un gesto dell'utente dell'estensione, ad esempio facendo clic sull'icona di azione. Oppure un'interazione di un utente su una pagina di estensione o uno script di contenuti, ad esempio il clic su un pulsante. Per una demo completa, vedi l'estensione di esempio Open Side Panel.

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. Usa windowId per aprire un riquadro laterale globale. In alternativa, imposta tabId in modo che apra 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 });
  }
});

Passa 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 una scheda diversa, questa la sostituisce con il 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.tabs.onActivated.addListener(async ({ tabId }) => {
  const { path } = await chrome.sidePanel.getOptions({ tabId });
  if (path === welcomePage) {
    chrome.sidePanel.setOptions({ path: mainPage });
  }
});

Per un esempio completo, consulta la sezione Più riquadri laterali.

Esperienza utente nel riquadro laterale

Gli utenti vedranno per primi i riquadri laterali integrati di Chrome. Ogni riquadro laterale mostra l'icona dell'estensione nel menu del riquadro laterale. Se non vengono incluse icone, viene visualizzata un'icona segnaposto con la prima lettera del nome dell'estensione.

Apri il riquadro laterale

Navigazione al menu del riquadro laterale
Gli utenti possono trovare i riquadri laterali disponibili nel menu del riquadro laterale. Quindi, possono scegliere un'estensione dal menu a discesa.
Menu a discesa del riquadro laterale
UI del riquadro laterale del browser Chrome.
Apri tramite un gesto dell'utente

Puoi aprire il riquadro laterale tramite le interazioni degli utenti utilizzando sidePanel.open() e sidePanel.setPanelBehavior(), ad esempio:

Esempi

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

Tipi

GetPanelOptions

Proprietà

  • tabId

    numero facoltativo

    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 tutte le schede che non hanno impostazioni specifiche).

OpenOptions

Chrome 116 e versioni successive

Proprietà

  • tabId

    numero facoltativo

    La scheda in cui aprire il riquadro laterale. Se la scheda corrispondente ha un riquadro laterale specifico per la scheda, il riquadro verrà aperto solo per quella scheda. Se non è presente un riquadro specifico, quello globale verrà aperto nella scheda specificata e in tutte le altre schede senza un riquadro specifico per le schede attualmente aperto. Verrà eseguito l'override di qualsiasi riquadro laterale attualmente attivo (globale o specifico di una scheda) nella scheda corrispondente. È necessario specificare almeno uno di questi valori o windowId.

  • windowId

    numero facoltativo

    La finestra in cui aprire il riquadro laterale. Questo vale solo se l'estensione ha un riquadro laterale globale (non specifico per le schede) o se è specificato anche tabId. Verrà eseguito l'override di qualsiasi riquadro laterale globale attivo che l'utente ha aperto nella finestra specificata. È necessario specificare almeno uno di questi valori o tabId.

PanelBehavior

Proprietà

  • openPanelOnActionClick

    booleano facoltativo

    Consente di fare clic sull'icona dell'estensione per attivare o disattivare la visualizzazione della voce dell'estensione nel riquadro laterale. Il valore predefinito è false.

PanelOptions

Proprietà

  • abilitata

    booleano facoltativo

    Indica se il riquadro laterale deve essere attivato. Questa opzione è facoltativa. Il valore predefinito è true.

  • percorso

    stringa facoltativo

    Il percorso del file HTML del riquadro laterale da utilizzare. Deve essere una risorsa locale all'interno del pacchetto dell'estensione.

  • tabId

    numero facoltativo

    Se specificato, le opzioni del riquadro laterale verranno applicate solo alla scheda con questo ID. Se omesse, queste opzioni impostano il comportamento predefinito (utilizzato per tutte le schede che non hanno impostazioni specifiche). Nota: se per questo tabId è impostato lo stesso percorso e per il tabId predefinito, il riquadro per questo tabId sarà un'istanza diversa da quella del riquadro per il tabId predefinito.

SidePanel

Proprietà

  • default_path

    stringa

    Percorso specificato dallo sviluppatore per la visualizzazione del riquadro laterale.

Metodi

getOptions()

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

Restituisce la configurazione del riquadro attiva.

Parametri

  • opzioni

    GetPanelOptions

    Specifica il contesto per cui restituire la configurazione.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (options: PanelOptions)=>void

Ritorni

  • Promise<PanelOptions>

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

getPanelBehavior()

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

Restituisce il comportamento corrente del riquadro laterale dell'estensione.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (behavior: PanelBehavior)=>void

Ritorni

  • Promise<PanelBehavior>

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

open()

Promise Chrome 116 o versioni successive 
chrome.sidePanel.open(
  options: OpenOptions,
  callback?: function,
)

Apre il riquadro laterale dell'estensione. Questa funzione può essere chiamata 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

Ritorni

  • Promise<void>

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso 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 riquadro.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

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

setPanelBehavior()

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

Configura il comportamento del riquadro laterale dell'estensione. Questa è un'operazione di upsert.

Parametri

  • dei consumatori

    PanelBehavior

    Il nuovo comportamento da impostare.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

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