Extensões na barra lateral do Microsoft Edge

Artigo
10/10/2023

Como desenvolvedor de extensão do Microsoft Edge, use este artigo para fazer com que sua extensão nova ou existente do Microsoft Edge apareça na barra lateral. Qualquer extensão pode usar a barra lateral além de sua outra interface do usuário.

A barra lateral de uma extensão do Microsoft Edge

Observação: o recurso de extensões de barra lateral está sendo implantado em uma base de usuários crescente para todos os canais do Microsoft Edge.

Usando a API da Barra Lateral para extensões, você pode aprimorar a experiência de navegação permitindo que os usuários exibam informações adicionais junto com o conteúdo main de uma página da Web.

A barra lateral é um painel persistente localizado na lateral do navegador, que coexiste com o conteúdo primário do navegador. A barra lateral reduz a necessidade de alternar constantemente entre as guias, resultando em uma experiência de navegação mais produtiva.

Opcionalmente, as extensões podem usar a API da barra lateral para mostrar uma interface do usuário personalizada na barra lateral do Microsoft Edge. As extensões podem continuar aparecendo na barra de ferramentas do Microsoft Edge junto com uma interface do usuário, como pop-ups, e podem injetar scripts, por exemplo.

Terminologia

Termo	Definição
API da barra lateral	Nome do recurso que você pode usar em suas extensões do Microsoft Edge. Os documentos do Chrome usam o painel lateral do termo.
`sidePanel` ou `side_panel`	Nome da API e permissão para habilitar qualquer extensão como uma extensão de barra lateral.
Extensão da barra lateral	Uma extensão do Microsoft Edge que tem uma interface do usuário na barra lateral.

Os recursos da API da Barra Lateral incluem:

A barra lateral permanece aberta enquanto navega entre as guias.
Uma extensão na barra lateral pode ser disponibilizada para sites específicos.
Uma extensão na barra lateral tem acesso a todas as APIs com suporte para extensões do Microsoft Edge.

Origin

Assim como acontece com outros recursos de extensão, a página da barra lateral se compromete com um contexto de extensão confiável em sua origem (extension://<id>). A barra lateral tem o mesmo acesso à API que outros contextos de extensão confiáveis.

Todas as APIs de extensões existentes estão disponíveis para extensões de barra lateral, para que você possa aproveitar todos os recursos atuais da estrutura de extensibilidade em sua extensão habilitada para barra lateral.

Adicionar a permissão sidePanel no arquivo de manifesto da extensão

Para usar a API da Barra Lateral, adicione uma permissão em seu manifest.json arquivo. Inclua a sidePanel permissão no arquivo da manifest.json extensão:

{
  ...
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidebar.html"
  },
  "permissions": [
    "sidePanel"
  ]
   ...
}

Cada extensão do Microsoft Edge tem um arquivo de manifesto formatado por JSON, chamado manifest.json. O arquivo de manifesto é o blueprint da sua extensão.

Veja também:

Formato de arquivo de manifesto para extensões

As seções a seguir demonstram alguns casos de uso comuns para a API da Barra Lateral.

Uma barra lateral pode ser definida como o padrão para mostrar a mesma extensão em todas as guias abertas do navegador. Os valores padrão persistem entre as sessões do navegador.

Em manifest.json, defina a "default_path" chave, como "sidebar.html":

{
  "name": "My sidebar extension",
  ...
  "side_panel": {
    "default_path": "sidebar.html"
  }
  ...
}

O arquivo especificado como o padrão, como sidebar.html, aparece em todas as guias abertas do navegador:

<!DOCTYPE html>
<html>
  <head>
    <title>My Sidebar</title>
  </head>
  <body>
    <h1>Sidebar extension for all sites</h1>
    <p>This sidebar is enabled on all sites</p>
  </body>
</html>

Uma extensão pode usar sidepanel.setOptions() para habilitar uma barra lateral em uma guia específica. Esse pode ser um site específico, portanto, a extensão é aberta na barra lateral quando o usuário vai para este site.

Este exemplo usa chrome.tabs.onUpdated() para ouvir todas as atualizações feitas na guia. Ele verifica se a URL é www.bing.com e, se for o caso, habilita a barra lateral. Caso contrário, desabilita a barra lateral.

Em service-worker.js, em addListener(), teste url.origin para ver se é a guia desejada e, em seguida, em sidePanel.setOptions(), definido enabled como true ou false:

const BING_ORIGIN = 'https://www.bing.com';

chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
  if (!tab.url) return;
  const url = new URL(tab.url);
  // Enables the sidebar when at bing.com
  if (url.origin === BING_ORIGIN) {
    await chrome.sidePanel.setOptions({
      tabId,
      path: 'sidepanel.html',
      enabled: true
    });
  } else {
    // Disables the sidebar when at other sites
    await chrome.sidePanel.setOptions({
      tabId,
      enabled: false
    });
  }
});

Quando um usuário muda para uma guia ou site para o qual a barra lateral não está habilitada, a barra lateral fica oculta.

Para obter um exemplo completo, consulte Exemplo de painel lateral específico do site.

Para permitir que os usuários abram a barra lateral clicando no ícone da barra de ferramentas de ação, use sidePanel.setPanelBehavior(). Primeiro, declare a "action" chave em manifest.json:

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

Em seguida, adicione o seguinte código à service-worker.js listagem de código que está em Habilitar uma barra lateral somente para um site específico, acima:

// Allow users to open the sidebar by clicking the action toolbar icon
chrome.sidePanel
  .setPanelBehavior({ openPanelOnActionClick: true })
  .catch((error) => console.error(error));

Uma extensão pode usar sidepanel.getOptions() para recuperar a barra lateral atual e habilitar uma barra lateral diferente para uma guia específica.

Este exemplo define uma barra lateral que contém uma mensagem de boas-vindas em runtime.onInstalled(). Quando o usuário navega para uma guia diferente, a barra lateral é substituída pela barra lateral no nível do navegador.

// service-worker.js:
const welcomePage = 'sidebar/welcome-sb.html';
const mainPage = 'sidebar/main-sb.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 });
  }
});

sidePanel.open() permite que as extensões abram a barra lateral por meio de um gesto do usuário, como clicar no ícone de ação ou por meio de qualquer interação do usuário em uma página de extensão ou script de conteúdo, como clicar em um botão.

O código a seguir mostra como abrir uma barra lateral global na janela atual quando o usuário clica em um menu de contexto. Ao usar sidePanel.open(), escolha o contexto no qual a barra lateral deve ser aberta:

Use windowId para abrir uma barra lateral global, conforme mostrado no exemplo a seguir.
Ou defina o tabId para abrir a barra lateral apenas em uma guia específica.

// service-worker.js:
chrome.runtime.onInstalled.addListener(() => {
  chrome.contextMenus.create({
    id: 'openSidePanel',
    title: 'Open sidebar',
    contexts: ['all']
  });
});

chrome.contextMenus.onClicked.addListener((info, tab) => {
  if (info.menuItemId === 'openSidePanel') {
    // Open the sidebar in all the tabs of the current window.
    chrome.sidePanel.open({ windowId: tab.windowId });
  }
});

As extensões na barra lateral do Microsoft Edge têm esses recursos de UX (experiência do usuário).

Há várias maneiras de o usuário abrir a extensão na barra lateral:

Clicando em um ícone

Os usuários podem clicar no ícone Abrir na barra lateral (), que é exibido ao lado do nome da extensão no hub Extensões:

Caixa de diálogo barra lateral

Ou os usuários podem clicar no ícone personalizado da extensão na barra de ferramentas, se ela estiver habilitada. Essa experiência de usuário exige que a extensão habilite o ícone de atalho para abrir a barra lateral, conforme descrito em Habilitar o ícone de atalho da extensão para abrir a barra lateral, acima. Neste exemplo, o ícone personalizado da extensão é um círculo ():

Clicando com o botão direito do mouse no ícone da extensão

Os usuários podem clicar com o botão direito do mouse no ícone da extensão na barra de ferramentas e, em seguida, selecionar Abrir na barra lateral ou Fechar barra lateral:

Clicando com o botão direito do mouse no atalho na barra de ferramentas para abrir a extensão

O ícone da extensão será exibido na barra de ferramentas se o usuário tiver clicado no ícone Mostrar na barra de ferramentas () ao lado do nome da extensão no hub Extensões.

Pressionando um atalho de teclado

Os usuários poderão pressionar um atalho de teclado, se o comando de ação estiver habilitado e o ícone de ação estiver habilitado para abrir a barra lateral.

Para habilitar o comando de ação, consulte Comandos de ação em chrome.commands na referência de API.
Para habilitar o ícone de ação, consulte Abrir o painel lateral clicando no ícone da barra de ferramentas no chrome.sidePanel na referência de API.

Se a openPanelOnActionClick() propriedade do tipo PanelBehavior estiver definida como true, o usuário poderá abrir a barra lateral usando um atalho de teclado. Para habilitar isso, especifique um comando de ação no manifesto.

Abrir por meio de um gesto

A barra lateral também pode ser aberta por meio das seguintes interações:

Abra a barra lateral por um gesto de usuário de extensão, como clicar no ícone de ação. Essa abordagem usa sidePanel.open(). Consulte Abrir a barra lateral após a interação do usuário, acima.
Abra a barra lateral clicando no ícone da barra de ferramentas. Essa abordagem usa sidePanel.setPanelBehavior(). Confira Clicando em um ícone na seção "Abrindo a extensão na barra lateral", acima.

Exemplos de extensão

Para obter mais demonstrações de extensões de API de barra lateral, explore qualquer uma das seguintes extensões:

Tipos e métodos

Consulte Tipos e Métodos na página de referência da API chrome.sidePanel em developer.chrome.com.

Confira também

Observação

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Google e usadas de acordo com os termos descritos na Licença Internacional de Atribuição do Creative Commons 4.0. A página original é encontrada aqui.

Este trabalho é licenciado sob uma Licença Internacional de Atribuição do Creative Commons 4.0.

Compartilhar via

Terminologia

Recursos da API da Barra Lateral

Origin

Adicionar a permissão sidePanel no arquivo de manifesto da extensão

Usar casos para a API da Barra Lateral

Exibir a mesma barra lateral em cada site

Habilitar uma barra lateral somente para um site específico

Habilitar o ícone de atalho da extensão para abrir a barra lateral

Alternar para uma barra lateral diferente

Abrir a barra lateral após a interação do usuário

Experiência do usuário de extensões de barra lateral

Abrindo a extensão na barra lateral