Descrição
Use as ações do navegador para colocar ícones da barra de ferramentas principal do Google Chrome, à direita da barra de endereço. Além do ícone, a ação do navegador pode ter uma dica, um selo e um pop-up.
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 nem sempre está 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 de extensões da seguinte 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 Chrome selecionará o ícone mais próximo e o dimensionará para o tamanho adequado para preencher o espaço de 16 dígitos. No entanto, se o tamanho exato não for fornecido, esse dimensionamento poderá fazer com que o ícone perca detalhes ou pareça impreciso.
Como dispositivos com fatores de escala menos comuns, como 1,5x ou 1,2x, estão se tornando mais comuns, recomendamos fornecer vários tamanhos para os ícones. Isso também garante que, se o tamanho de exibição do ícone for mudado, 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 selo e um pop-up.
Icon
Os ícones de ação do navegador no Chrome têm 16 quedas (pixels independentes de dispositivo) de largura e altura. Ícones maiores são redimensionados para caber, mas, para ter melhores resultados, use um ícone quadrado de 16 polegadas.
É possível definir o ícone de duas maneiras: usando uma imagem estática ou o elemento de tela HTML5. Usar imagens estáticas é mais fácil para aplicativos simples, mas você pode criar IUs mais dinâmicas, como animação suave, usando o elemento de tela.
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 precisam estar no formato PNG.
Para definir o ícone, use o campo default_icon do default_icon no manifesto ou chame o método browserAction.setIcon
.
Para exibir 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 a ser
mostrada vai ser selecionada no conjunto para se ajustar melhor ao tamanho do pixel de 16 queda. O conjunto de ícones pode conter
qualquer tamanho de ícone, e o Chrome selecionará o ícone mais adequado.
Dica
Para definir a dica, use o campo default_title do default_title no manifesto ou
chame o método browserAction.setTitle
. Você pode especificar strings específicas da localidade para o campo
default_title. Consulte Internacionalização para ver mais detalhes.
Selo
As ações do navegador podem exibir um selo, um trecho 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 selo tem espaço limitado, ele deve 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. Ela pode conter o conteúdo HTML que você quiser, e é automaticamente dimensionada 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 dele. Especifique o arquivo HTML no campo default_popup de default_popup no manifesto ou chame o método browserAction.setPopup
.
Dicas
Para ter o melhor impacto visual, siga estas diretrizes:
- Use as ações do navegador para recursos relevantes na maioria das páginas.
- Não use ações do navegador para recursos que fazem sentido apenas para algumas páginas. Em vez disso, use ações de página.
- Use ícones grandes e coloridos que aproveitem ao máximo o espaço de dip de 16x16. 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 do menu monocromático do Google Chrome. Isso não funciona bem com os temas 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 bonito em uma variedade de cores de fundo.
- Não anime seu ícone constantemente. Isso é chato.
Exemplos
Você pode encontrar exemplos simples de como usar ações do navegador no diretório examples/api/browserAction. Para ver outros exemplos e receber ajuda na visualização do 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
Propriedades
-
tabId
número opcional
O ID da guia para consultar o estado. Se nenhuma guia for especificada, o estado não específico de tabulação será retornado.
Métodos
disable()
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 em que a ação do navegador será modificada.
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
enable()
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 em que a ação do navegador será modificada.
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Recebe a cor de fundo da ação do navegador.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: ColorArray) => void
-
resultado
-
Retorna
-
Promise<ColorArray>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
Recebe o texto do ícone da ação do navegador. Se nenhuma guia for especificada, o texto do símbolo não específico da guia será retornado.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Recebe o documento HTML que está definido como o pop-up para esta ação do navegador.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Recebe o título da ação do navegador.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Define a cor de plano de fundo do selo.
Parâmetros
-
detalhes
objeto
-
color
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 em opacidade total. -
tabId
número opcional
Limita a mudança a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
Define o texto do ícone para a ação do navegador. O selo é exibido na parte superior do ícone.
Parâmetros
-
detalhes
objeto
-
tabId
número opcional
Limita a mudança a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
texto
string opcional
Qualquer número de caracteres pode ser transmitido, mas apenas cerca de quatro cabem no espaço. Se uma string vazia (
''
) for transmitida, o texto do selo será apagado. SetabId
for especificado etext
for nulo, o texto da guia especificada será apagado, e o padrão será o texto do selo global.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setIcon()
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 de acordo com a densidade de pixels da tela. Se o número de pixels de imagem que cabem em uma unidade de espaço de tela for igual a
scale
, uma imagem com tamanhoscale
* 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 -> relative image path} que aponta para um ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem usada será escolhida de acordo com a densidade de pixels da tela. Se o número de pixels de imagem que cabem em uma unidade de espaço de tela for igual a
scale
, uma imagem com tamanhoscale
* 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 a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 116 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
Define o documento HTML para 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 a ser exibido em um pop-up. Se definido como a string vazia (
''
), nenhum pop-up será mostrado. -
tabId
número opcional
Limita a mudança a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
setTitle()
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 a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
title
string
A string que a ação do navegador deve exibir ao passar o mouse sobre ela.
-
-
callback
função optional
Chrome 67 ou mais recenteO parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 88 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.