chrome.browserAction

Descrição

Disponibilidade

Na figura a seguir, o quadrado multicolorido à direita da barra de endereço é o ícone de uma ação do navegador. Um pop-up aparece abaixo do ícone.

Se você quiser criar um ícone que não esteja sempre ativo, use uma ação de página em vez de uma ação do navegador.

Manifesto

Registre a ação do navegador no manifesto da extensão desta forma:

{   "name": "My extension",   ...   "browser_action": {     "default_icon": {                // optional       "16": "images/icon16.png",     // optional       "24": "images/icon24.png",     // optional       "32": "images/icon32.png"      // optional     },     "default_title": "Google Mail",  // optional, shown in tooltip     "default_popup": "popup.html"    // optional   },   ... } 

Você pode fornecer um ícone de qualquer tamanho para ser usado no Chrome, e o navegador vai selecionar o mais próximo e dimensioná-lo para o tamanho adequado para preencher o espaço de 16 dips. No entanto, se o tamanho exato não for fornecido, esse dimensionamento poderá fazer com que o ícone perca detalhes ou fique borrado.

Como os dispositivos com fatores de escala menos comuns, como 1,5x ou 1,2x, estão se tornando mais comuns, recomendamos que você forneça vários tamanhos para seus ícones. Isso também garante que, se o tamanho de exibição do ícone for alterado, você não precisará fazer mais nada para fornecer ícones diferentes.

A sintaxe antiga para registrar o ícone padrão ainda é compatível:

{   "name": "My extension",   ...   "browser_action": {     ...     "default_icon": "images/icon32.png"  // optional     // equivalent to "default_icon": { "32": "images/icon32.png" }   },   ... } 

Partes da interface

Uma ação do navegador pode ter um ícone, uma dica, um indicador e um pop-up.

Ícone

Os ícones de ação do navegador no Chrome têm 16 dips (pixels independentes de dispositivo) de largura e altura. Ícones maiores são redimensionados para caber, mas para melhores resultados, use um ícone quadrado de 16 dips.

É possível definir o ícone de duas maneiras: usando uma imagem estática ou o elemento canvas do HTML5. Usar imagens estáticas é mais fácil para aplicativos simples, mas é possível criar interfaces mais dinâmicas, como animações suaves, usando o elemento canvas.

As imagens estáticas podem estar em qualquer formato que o WebKit possa mostrar, incluindo BMP, GIF, ICO, JPEG ou PNG. Para extensões descompactadas, as imagens precisam estar no formato PNG.

Para definir o ícone, use o campo default_icon de browser_action no manifest ou chame o método browserAction.setIcon.

Para mostrar o ícone corretamente quando a densidade de pixels da tela (proporção size_in_pixel / size_in_dip) é diferente de 1, ele pode ser definido como um conjunto de imagens com tamanhos diferentes. A imagem real a ser mostrada será selecionada no conjunto para se ajustar melhor ao tamanho de pixel de 16 dip. O conjunto de ícones pode conter especificações de ícones de qualquer tamanho, e o Chrome vai selecionar a mais adequada.

Dica

Para definir a dica, use o campo default_title de browser_action no manifesto ou chame o método browserAction.setTitle. É possível especificar strings específicas de localidade para o campo default_title. Consulte Internacionalização para mais detalhes.

Selo

As ações do navegador podem mostrar um badge (um pouco de texto sobreposto ao ícone). Os selos facilitam a atualização da ação do navegador para mostrar uma pequena quantidade de informações sobre o estado da extensão.

Como o espaço do selo é limitado, ele precisa ter até quatro caracteres.

Defina o texto e a cor do selo usando browserAction.setBadgeText e browserAction.setBadgeBackgroundColor, respectivamente.

Pop-up

Se uma ação do navegador tiver um pop-up, ele vai aparecer quando o usuário clicar no ícone da extensão. O pop-up pode conter qualquer conteúdo HTML que você quiser e é dimensionado automaticamente para se ajustar ao conteúdo. O pop-up não pode ser menor que 25 x 25 nem maior que 800 x 600.

Para adicionar um pop-up à ação do navegador, crie um arquivo HTML com o conteúdo do pop-up. Especifique o arquivo HTML no campo default_popup de browser_action no manifest ou chame o método browserAction.setPopup.

Dicas

Para ter o melhor impacto visual, siga estas diretrizes:

• Use ações do navegador para recursos que fazem sentido na maioria das páginas.
• Não use ações do navegador para recursos que fazem sentido apenas para algumas páginas. Use page actions.
• Use ícones grandes e coloridos que aproveitam ao máximo o espaço de 16 x 16 dip. Os ícones de ação do navegador devem parecer um pouco maiores e mais pesados do que os ícones de ação da página.
• Não tente imitar o ícone monocromático do menu do Google Chrome. Isso não funciona bem com temas e, de qualquer forma, as extensões precisam se destacar um pouco.
• Use a transparência alfa para adicionar bordas suaves ao ícone. Como muitas pessoas usam temas, seu ícone precisa ficar bom em várias cores de plano de fundo.
• Não anime o ícone constantemente. Isso é irritante.

Exemplos

Confira exemplos simples de uso de ações do navegador no diretório examples/api/browserAction. Para outros exemplos e ajuda para ver o código-fonte, consulte Exemplos.

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

chrome.browserAction.onClicked.addListener(
  callback: function,
)