Esta página foi traduzida pela API Cloud Translation.

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

&leq; 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.

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.

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<ColorArray>

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

chrome.browserAction

Descrição

Disponibilidade

Manifesto

Partes da interface

Ícone

Dica

Selo

Pop-up

Dicas

Exemplos

Tipos

ColorArray

Tipo

ImageDataType

Tipo

TabDetails

Propriedades

Métodos

disable()

Parâmetros

Retorna

enable()

Parâmetros

Retorna

getBadgeBackgroundColor()

Parâmetros

Retorna

getBadgeText()

Parâmetros

Retorna

getPopup()

Parâmetros

Retorna

getTitle()

Parâmetros

Retorna

setBadgeBackgroundColor()

Parâmetros

Retorna

setBadgeText()

Parâmetros

Retorna

setIcon()

Parâmetros

Retorna

setPopup()

Parâmetros

Retorna

setTitle()

Parâmetros

Retorna

Eventos

onClicked

Parâmetros