chrome.browserAction

Descrição

Use as ações do navegador para colocar ícones na barra de ferramentas principal do Google Chrome, à direita da barra de endereço. Além do ícone, uma ação do navegador pode ter uma dica, um selo e um pop-up.

Disponibilidade

≤ MV2

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 nem sempre está ativo, use uma ação de página em vez de um navegador. à ação.

Manifesto

Registre a ação do navegador no manifesto de extensões desta maneira:

{
  "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 ícones de qualquer tamanho para serem usados no Chrome, e este selecionará o ícone mais próximo e a escala para o tamanho adequado para preencher o espaço de 16 imersão. No entanto, se o tamanho exato não for fornecido, pode fazer com que o ícone perca detalhes ou pareça confuso.

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

A sintaxe antiga para registro do í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 selo e um pop-up.

Ícone

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

É possível definir o ícone de duas maneiras: usando uma imagem estática ou o elemento de tela HTML5. Usando imagens estáticas é mais fácil para aplicativos simples, mas você pode criar interfaces do usuário mais dinâmicas, como animação suave usando o elemento canvas.

As imagens estáticas podem estar em qualquer formato que o WebKit possa exibir, incluindo BMP, GIF, ICO, JPEG ou PNG. Para extensões descompactadas, as imagens devem 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 pixel da tela (proporção size_in_pixel / size_in_dip) for diferente de 1, o ícone pode ser definido como um conjunto de imagens com tamanhos diferentes. A imagem real que será display será selecionado no conjunto para ajustar melhor o tamanho do pixel de 16 quedas. O conjunto de ícones pode conter qualquer especificação de tamanho de ícone, e o Chrome selecionará a mais adequada.

Dica

Para definir a dica, use o campo default_title de default_title no manifesto ou chame o método browserAction.setTitle. Você pode especificar strings específicas de localidade para o default_title consulte Internacionalização para mais detalhes.

Selo

As ações do navegador podem opcionalmente exibir um selo, um trecho de texto sobre o ícone. Os selos facilitam a atualização da ação do navegador para exibir uma pequena quantidade de informações sobre o estado da extensão.

Como o selo tem espaço limitado, ele deve ter quatro caracteres ou menos.

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

Pop-up

Se uma ação do navegador tiver um pop-up, ele aparecerá quando o usuário clicar no ícone da extensão. A O pop-up pode conter qualquer conteúdo HTML que você quiser e é dimensionado automaticamente para caber em seu 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 default_popup do manifesto ou chamar o método browserAction.setPopup.

Dicas

Para obter o melhor impacto visual, siga estas diretrizes:

• Use as 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. Usar a página ações.
• Use ícones grandes e coloridos que aproveitem ao máximo o espaço de 16 x 16 quedas. Ícones de ação do navegador devem parecer um pouco maiores e mais pesados do que ícones de ação da página.
• Não tente imitar o ícone de menu monocromático do Google Chrome. Isso não funciona bem com e, de qualquer maneira, as extensões devem se destacar um pouco.
• Use a transparência Alfa para adicionar bordas suaves ao ícone. Como muitas pessoas usam temas, seu ícone deve ficar bom em uma variedade de cores de fundo.
• Não anime o ícone constantemente. Isso é chato.

Exemplos

Confira exemplos simples de como usar ações do navegador em examples/api/browserAction diretório. Para ver outros exemplos e receber ajuda para visualizar o código-fonte, consulte Amostras.

Tipos

ColorArray

Tipo

[número, número, número, número]

ImageDataType

Dados de pixel de uma imagem. Precisa ser um objeto ImageData. por exemplo, de um elemento canvas.

Tipo

ImageData

TabDetails

Chrome 88 ou superior

Propriedades

• tabId

  número opcional

  O ID da guia em que o estado da consulta será consultado. Se nenhuma guia for especificada, o estado não específico da guia será retornado.

Métodos

disable()

Promessa

chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Desativa a ação do navegador para uma guia.

Parâmetros

• tabId

  número opcional

  O ID da guia para modificar a ação do navegador.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

enable()

Promessa

chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

Ativa a ação do navegador para uma guia. O padrão é ativado.

Parâmetros

• tabId

  número opcional

  O ID da guia para modificar a ação do navegador.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getBadgeBackgroundColor()

Promessa

chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

Recupera a cor de fundo da ação do navegador.

Parâmetros

• detalhes

  TabDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: ColorArray) => void

  • resultado

    ColorArray

Retorna

• Promise&lt;ColorArray&gt;

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getBadgeText()

Promessa

chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

Recebe o texto do símbolo da ação do navegador. Se nenhuma guia for especificada, o texto do selo não específico da guia será retornado.

Parâmetros

• detalhes

  TabDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: string) => void

  • resultado

    string

Retorna

• Promessa<string>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getPopup()

Promessa

chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

Extrai o documento HTML definido como o pop-up para essa ação do navegador.

Parâmetros

• detalhes

  TabDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: string) => void

  • resultado

    string

Retorna

• Promessa<string>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getTitle()

Promessa

chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Extrai o título da ação do navegador.

Parâmetros

• detalhes

  TabDetails

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  (result: string) => void

  • resultado

    string

Retorna

• Promessa<string>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setBadgeBackgroundColor()

Promessa

chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Define a cor do plano de fundo do selo.

Parâmetros

• detalhes

  objeto

  • cor

    string | ColorArray

    Uma matriz de quatro números inteiros no intervalo de 0 a 255 que compõem a cor RGBA do selo. Também pode ser uma string com um valor de cor hexadecimal CSS. por exemplo, #FF0000 ou #F00 (vermelho). Renderiza cores na opacidade total.

  • tabId

    número opcional

    Limita a mudança quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setBadgeText()

Promessa

chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Define o texto do símbolo para a ação do navegador. O selo aparece na parte de cima do ícone.

Parâmetros

• detalhes

  objeto

  • tabId

    número opcional

    Limita a mudança quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.

  • texto

    string opcional

    Qualquer número de caracteres pode ser transmitido, mas apenas cerca de quatro podem caber no espaço. Se uma string vazia ('') for transmitida, o texto do selo será apagado. Se tabId for especificado e text for nulo, o texto da guia especificada será apagado, e o padrão será o texto do selo global.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setIcon()

Promessa

chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

Define o ícone da ação do navegador. O ícone pode ser especificado como o caminho para um arquivo de imagem, como os dados de pixel de um elemento de tela ou como um dicionário de um desses elementos. A propriedade path ou imageData precisa ser especificada.

Parâmetros

• detalhes

  objeto

  • imageData

    ImageData | objeto opcional

    Um objeto ImageData ou um dicionário {size -> ImageData} que representa um ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem usada será escolhida dependendo da densidade de pixels da tela. Se o número de pixels da imagem que cabem em uma unidade de espaço na tela for igual a scale, uma imagem com tamanho scale * n será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe que "details.imageData = foo" é equivalente a 'details.imageData = {'16': foo}'

  • caminho

    string | objeto opcional

    Um caminho de imagem relativo ou um dicionário {size -> caminho da imagem relativa} apontando para um ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem usada será escolhida dependendo da densidade de pixels da tela. Se o número de pixels da imagem que cabem em uma unidade de espaço na tela for igual a scale, uma imagem com tamanho scale * n será selecionada, em que n é o tamanho do ícone na interface. É necessário especificar pelo menos uma imagem. Observe que "details.path = foo" é equivalente a 'details.path = {'16': foo}'

  • tabId

    número opcional

    Limita a mudança quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.

• callback

  função opcional

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 116 ou versões mais recentes

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setPopup()

Promessa

chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

Define o documento HTML que será aberto como um pop-up quando o usuário clicar no ícone de ação do navegador.

Parâmetros

• detalhes

  objeto

  • pop-up

    string

    O caminho relativo para o arquivo HTML que será mostrado em um pop-up. Se definida como a string vazia (''), nenhum pop-up será exibido.

  • tabId

    número opcional

    Limita a mudança quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

setTitle()

Promessa

chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

Define o título da ação do navegador. Esse título aparece na dica.

Parâmetros

• detalhes

  objeto

  • tabId

    número opcional

    Limita a mudança quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.

  • título

    string

    A string que a ação do navegador deve exibir quando o mouse é passado.

• callback

  função opcional

  Chrome 67 ou superior

  O parâmetro callback tem esta aparência:

  () => void

Retorna

• Promessa<void>

  Chrome 88 ou superior

  As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onClicked

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

Disparado quando um ícone de ação do navegador é clicado. Não será acionado se a ação do navegador tiver um pop-up.

Parâmetros

• callback

  função

  O parâmetro callback tem esta aparência:

  (tab: tabs.Tab) => void

  • tab

    tabs.Tab