chrome.sidePanel

Descrição

Use a API chrome.sidePanel para hospedar conteúdo no painel lateral do navegador ao lado do conteúdo principal de uma página da Web.

Permissões

sidePanel

Para usar a API Side Panel, adicione a permissão "sidePanel" ao arquivo manifest da extensão:

manifest.json:

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

Disponibilidade

Chrome 114+ MV3+

Conceitos e uso

A API Side Panel permite que as extensões mostrem a própria interface no painel lateral, possibilitando experiências persistentes que complementam a jornada de navegação do usuário.

Menu suspenso do painel lateral
Interface do painel lateral do navegador Chrome.

Alguns recursos incluem:

  • O painel lateral permanece aberto ao navegar entre guias (se estiver configurado para isso).
  • Ele pode estar disponível apenas em sites específicos.
  • Como uma página de extensão, os painéis laterais têm acesso a todas as APIs do Chrome.
  • Nas configurações do Chrome, os usuários podem especificar em qual lado o painel deve ser exibido.

Casos de uso

As seções a seguir demonstram alguns casos de uso comuns da API Side Panel. Consulte Exemplos de extensões para ver exemplos completos.

Mostrar o mesmo painel lateral em todos os sites

O painel lateral pode ser definido inicialmente pela propriedade "default_path" na chave "side_panel" do manifesto para mostrar o mesmo painel lateral em todos os sites. Ele precisa apontar para um caminho relativo no diretório da extensão.

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>

Ativar um painel lateral em um site específico

Uma extensão pode usar sidepanel.setOptions() para ativar um painel lateral em uma guia específica. Este exemplo usa chrome.tabs.onUpdated() para detectar atualizações feitas na guia. Ele verifica se o URL é www.google.com e ativa o painel lateral. Caso contrário, ele será desativado.

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 um usuário muda temporariamente para uma guia em que o painel lateral não está ativado, ele fica oculto. Ele vai aparecer de novo automaticamente quando o usuário mudar para uma guia em que estava aberto.

Quando o usuário navega até um site em que o painel lateral não está ativado, ele é fechado, e a extensão não aparece no menu suspenso do painel lateral.

Para um exemplo completo, consulte a amostra Painel lateral específico da guia.

Clique no ícone da barra de ferramentas para abrir o painel lateral

Os desenvolvedores podem permitir que os usuários abram o painel lateral ao clicar no ícone da barra de ferramentas de ação com sidePanel.setPanelBehavior(). Primeiro, declare a chave "action" no manifesto:

manifest.json:

{
  "name": "My side panel extension",
  ...
  "action": {
    "default_title": "Click to open panel"
  },
  ...
}

Agora, adicione este código ao exemplo anterior:

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

Abrir o painel lateral de forma programática na interação do usuário

O Chrome 116 apresenta o sidePanel.open(). Ele permite que as extensões abram o painel lateral por um gesto do usuário, como clicar no ícone de ação. Ou uma interação do usuário em uma página de extensão ou um script de conteúdo, como clicar em um botão. Para uma demonstração completa, consulte a extensão de exemplo Abrir painel lateral.

O código a seguir mostra como abrir um painel lateral global na janela atual quando o usuário clica em um menu de contexto. Ao usar sidePanel.open(), você precisa escolher o contexto em que ele será aberto. Use windowId para abrir um painel lateral global. Outra opção é definir tabId para abrir o painel lateral apenas em uma guia específica.

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

Mudar para outro painel

As extensões podem usar sidepanel.getOptions() para recuperar o painel lateral atual. O exemplo a seguir define um painel lateral de boas-vindas em runtime.onInstalled(). Quando o usuário navega para outra guia, ela é substituída pelo painel lateral 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 });
  }
});

Consulte o exemplo Vários painéis laterais para conferir o código completo.

Experiência do usuário no painel lateral

Os usuários vão ver primeiro os painéis laterais integrados do Chrome. Cada painel lateral mostra o ícone da extensão no menu do painel lateral. Se nenhum ícone for incluído, um ícone marcador de posição vai aparecer com a primeira letra do nome da extensão.

Abrir o painel lateral

Para permitir que os usuários abram o painel lateral, use um ícone de ação em combinação com sidePanel.setPanelBehavior(). Outra opção é fazer uma chamada para sidePanel.open() após uma interação do usuário, como:

Fixar o painel lateral

Ícone de fixação na interface do painel lateral.
Ícone de fixar na interface do painel lateral.

A barra de ferramentas do painel lateral mostra um ícone de fixação quando o painel está aberto. Ao clicar no ícone, você fixa o ícone de ação da extensão. Clicar no ícone de ação uma vez fixado vai realizar a ação padrão do ícone e só abrir o painel lateral se isso tiver sido configurado explicitamente.

Exemplos

Para mais demonstrações de extensões da API Side Panel, confira qualquer uma das seguintes extensões:

Tipos

GetPanelOptions

Propriedades

  • tabId

    number optional

    Se especificado, as opções do painel lateral da guia em questão serão retornadas. Caso contrário, retorna as opções padrão do painel lateral (usadas para qualquer guia que não tenha configurações específicas).

OpenOptions

Chrome 116 ou mais recente

Propriedades

  • tabId

    number optional

    A guia em que o painel lateral será aberto. Se a guia correspondente tiver um painel lateral específico, ele só vai ficar aberto para essa guia. Se não houver um painel específico da guia, o painel global será aberto na guia especificada e em qualquer outra guia sem um painel específico aberto no momento. Isso vai substituir qualquer painel lateral ativo (global ou específico da guia) na guia correspondente. É preciso fornecer pelo menos um destes dados ou windowId.

  • windowId

    number optional

    A janela em que o painel lateral será aberto. Isso só se aplica se a extensão tiver um painel lateral global (não específico da guia) ou se tabId também for especificado. Isso vai substituir qualquer painel lateral global aberto na janela. É preciso fornecer pelo menos um destes dados ou tabId.

PanelBehavior

Propriedades

  • openPanelOnActionClick

    booleano opcional

    Se clicar no ícone da extensão vai alternar a exibição da entrada dela no painel lateral. O padrão é "false".

PanelLayout

Pendente

Propriedades

PanelOptions

Propriedades

  • ativado

    booleano opcional

    Se o painel lateral deve ser ativado. Isso é opcional. O valor padrão é true.

  • caminho

    string opcional

    O caminho para o arquivo HTML do painel lateral a ser usado. Precisa ser um recurso local no pacote de extensão.

  • tabId

    number optional

    Se especificado, as opções do painel lateral serão aplicadas apenas à guia com esse ID. Se omitidas, essas opções definem o comportamento padrão (usado para qualquer guia sem configurações específicas). Observação: se o mesmo caminho for definido para esse tabId e o tabId padrão, o painel desse tabId será uma instância diferente do painel do tabId padrão.

Side

Pendente

Define o possível alinhamento do painel lateral na interface do navegador.

Enumeração

"left"

"direita"

SidePanel

Propriedades

  • default_path

    string

    Caminho especificado pelo desenvolvedor para exibição do painel lateral.

Métodos

getLayout()

Promise Pendente
chrome.sidePanel.getLayout(
  callback?: function,
)

Retorna o layout atual do painel lateral.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (layout: PanelLayout) => void

Retorna

  • Promise<PanelLayout>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.

getOptions()

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

Retorna a configuração do painel ativo.

Parâmetros

  • opções

    GetPanelOptions

    Especifica o contexto para retornar a configuração.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (options: PanelOptions) => void

Retorna

  • Promise<PanelOptions>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.

getPanelBehavior()

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

Retorna o comportamento atual do painel lateral da extensão.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (behavior: PanelBehavior) => void

Retorna

  • Promise<PanelBehavior>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.

open()

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

Abre o painel lateral da extensão. Isso só pode ser chamado em resposta a uma ação do usuário.

Parâmetros

  • opções

    OpenOptions

    Especifica o contexto em que o painel lateral será aberto.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.

setOptions()

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

Configura o painel lateral.

Parâmetros

  • opções

    PanelOptions

    As opções de configuração a serem aplicadas ao painel.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.

setPanelBehavior()

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

Configura o comportamento do painel lateral da extensão. Essa é uma operação de upsert.

Parâmetros

  • comportamento do consumidor

    PanelBehavior

    O novo comportamento a ser definido.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    As promessas são compatíveis com o Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido ao callback.