chrome.action

Descrição

Use a API chrome.action para controlar o ícone da extensão na barra de ferramentas do Google Chrome.

Os ícones de ação aparecem na barra de ferramentas do navegador ao lado da caixa de pesquisa omnibox. Após a instalação, eles aparecem no menu de extensões (ícone de peça de quebra-cabeça). Os usuários podem fixar o ícone da extensão na barra de ferramentas.

Disponibilidade

Chrome 88+ MV3+

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"action"

Para usar a API chrome.action, especifique um "manifest_version" de 3 e inclua a chave "action" no arquivo de manifesto.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

A chave "action" (com as filhas) é opcional. Quando não está incluído, a extensão ainda aparece na barra de ferramentas para fornecer acesso ao menu dela. Por esse motivo, recomendamos que você sempre inclua pelo menos as chaves "action" e "default_icon".

Conceitos e uso

Partes da interface

Ícone

O ícone é a imagem principal na barra de ferramentas da sua extensão e é definido pela chave "default_icon" na chave "action" do manifesto. Os ícones precisam ter 16 pixels independentes do dispositivo (DIPs) de largura e altura.

A chave "default_icon" é um dicionário de tamanhos para caminhos de imagem. O Chrome usa esses ícones para escolher qual escala de imagem usar. Se não for encontrada uma correspondência exata, o Chrome vai selecionar a mais próxima disponível e dimensioná-la para se ajustar à imagem, o que pode afetar a qualidade da imagem.

Como 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 protege sua extensão contra possíveis mudanças no tamanho de exibição do ícone. No entanto, se você fornecer apenas um tamanho, a chave "default_icon" também poderá ser definida como uma string com o caminho para um único ícone em vez de um dicionário.

Também é possível chamar action.setIcon() para definir o ícone da extensão de forma programática, especificando um caminho de imagem diferente ou fornecendo um ícone gerado dinamicamente usando o elemento de tela HTML ou, se estiver configurando de um worker de serviço de extensão, a API tela fora da tela.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

Para extensões empacotadas (instaladas em um arquivo .crx), as imagens podem estar na maioria dos formatos que o mecanismo de renderização do Blink pode mostrar, incluindo PNG, JPEG, BMP, ICO e outros. O SVG não é compatível. As extensões descompactadas precisam usar imagens PNG.

Dica (título)

A dica ou o título aparece quando o usuário mantém o cursor do mouse sobre o ícone da extensão na barra de ferramentas. Ele também é incluído no texto acessível falado pelos leitores de tela quando o botão recebe foco.

A dica de ferramenta padrão é definida usando o campo "default_title" da chave "action" em manifest.json. Também é possível definir de forma programática chamando action.setTitle().

Selo

As ações podem mostrar um "selo", um pouco de texto sobreposto ao ícone. Isso permite atualizar a ação para mostrar uma pequena quantidade de informações sobre o estado da extensão, como um contador. O selo tem um componente de texto e uma cor de plano de fundo. Como o espaço é limitado, recomendamos que o texto do selo tenha quatro caracteres ou menos.

Para criar um selo, defina-o de forma programática chamando action.setBadgeBackgroundColor() e action.setBadgeText(). Não há uma configuração de selo padrão no manifesto. Os valores de cor do selo podem ser uma matriz de quatro números inteiros entre 0 e 255 que compõem a cor RGBA do selo ou uma string com um valor de cor CSS.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Um pop-up de ação é mostrado quando o usuário clica no botão de ação da extensão na barra de ferramentas. O pop-up pode conter qualquer conteúdo HTML que você quiser e será dimensionado automaticamente para caber no conteúdo. O tamanho do pop-up precisa estar entre 25 x 25 e 800 x 600 pixels.

O pop-up é inicialmente definido pela propriedade "default_popup" na chave "action" no arquivo manifest.json. Se presente, essa propriedade precisa apontar para um caminho relativo no diretório de extensão. Ele também pode ser atualizado dinamicamente para apontar para um caminho relativo diferente usando o método action.setPopup().

Casos de uso

Estado por guia

As ações de extensão podem ter estados diferentes para cada guia. Para definir um valor para uma guia individual, use a propriedade tabId nos métodos de configuração da API action. Por exemplo, para definir o texto do selo de uma guia específica, faça o seguinte:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

Se a propriedade tabId for omitida, a configuração será tratada como global. As configurações específicas da guia têm prioridade sobre as globais.

Estado ativado

Por padrão, as ações da barra de ferramentas são ativadas (clicáveis) em todas as guias. É possível mudar esse padrão definindo a propriedade default_state na chave action do manifesto. Se default_state for definido como "disabled", a ação será desativada por padrão e precisará ser ativada programaticamente para ser clicável. Se default_state for definido como "enabled" (padrão), a ação será ativada e clicável por padrão.

É possível controlar o estado de maneira programática usando os métodos action.enable() e action.disable(). Isso afeta apenas se o pop-up (se houver) ou o evento action.onClicked é enviado à sua extensão. Não afeta a presença da ação na barra de ferramentas.

Exemplos

Os exemplos a seguir mostram algumas maneiras comuns de usar ações em extensões. Para testar essa API, instale o exemplo da API Action do repositório chrome-extension-samples.

Mostrar um pop-up

É comum que uma extensão mostre um pop-up quando o usuário clica na ação dela. Para implementar isso na sua própria extensão, declare o pop-up no manifest.json e especifique o conteúdo que o Chrome vai mostrar no pop-up.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

Injete um script de conteúdo ao clicar

Um padrão comum para extensões é expor o recurso principal usando a ação dela. O exemplo abaixo demonstra esse padrão. Quando o usuário clica na ação, a extensão injeta um script de conteúdo na página atual. O script de conteúdo mostra um alerta para verificar se tudo funcionou conforme o esperado.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

Emular ações com declarativeContent

Este exemplo mostra como a lógica em segundo plano de uma extensão pode (a) desativar uma ação por padrão e (b) usar declarativeContent para ativar a ação em sites específicos.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

Tipos

OpenPopupOptions

Chrome 99 e versões mais recentes

Propriedades

  • windowId

    número opcional

    O ID da janela em que o pop-up de ação será aberto. Se não for especificado, o padrão será a janela ativa no momento.

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 da guia será retornado.

UserSettings

Chrome 91 e versões mais recentes

O conjunto de configurações especificadas pelo usuário relacionadas à ação de uma extensão.

Propriedades

  • isOnToolbar

    booleano

    Indica se o ícone de ação da extensão está visível na barra de ferramentas de nível superior das janelas do navegador, ou seja, se a extensão foi "fixada" pelo usuário.

UserSettingsChange

Chrome 130 e versões mais recentes

Propriedades

  • isOnToolbar

    booleano opcional

    Indica se o ícone de ação da extensão está visível na barra de ferramentas de nível superior das janelas do navegador, ou seja, se a extensão foi "fixada" pelo usuário.

Métodos

disable()

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

Desativa a ação de uma guia.

Parâmetros

  • tabId

    número opcional

    O ID da guia em que você quer modificar a ação.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

enable()

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

Ativa a ação de uma guia. Por padrão, as ações estão ativadas.

Parâmetros

  • tabId

    número opcional

    O ID da guia em que você quer modificar a ação.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getBadgeBackgroundColor()

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

Recebe a cor de plano de fundo da ação.

Parâmetros

Retorna

  • As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getBadgeText()

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

Recebe o texto do selo da ação. Se nenhuma guia for especificada, o texto do selo não específico da guia será retornado. Se displayActionCountAsBadgeText estiver ativado, um texto de marcador de posição será retornado, a menos que a permissão declarativeNetRequestFeedback esteja presente ou que o texto do selo específico da guia tenha sido fornecido.

Parâmetros

  • detalhes

    TabDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: string) => void

    • resultado

      string

Retorna

  • Promise<string>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getBadgeTextColor()

Promessa Chrome 110 e mais recentes 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

Recebe a cor do texto da ação.

Parâmetros

Retorna

  • As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getPopup()

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

Consegue o documento HTML definido como o pop-up para essa ação.

Parâmetros

  • detalhes

    TabDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: string) => void

    • resultado

      string

Retorna

  • Promise<string>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getTitle()

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

Recebe o título da ação.

Parâmetros

  • detalhes

    TabDetails

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (result: string) => void

    • resultado

      string

Retorna

  • Promise<string>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getUserSettings()

Promessa Chrome 91+ 
chrome.action.getUserSettings(
  callback?: function,
)

Retorna as configurações especificadas pelo usuário relacionadas à ação de uma extensão.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (userSettings: UserSettings) => void

Retorna

  • Promise<UserSettings>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

isEnabled()

Promessa Chrome 110 e mais recentes 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

Indica se a ação de extensão está ativada para uma guia (ou globalmente se nenhum tabId for fornecido). As ações ativadas usando apenas declarativeContent sempre retornam "false".

Parâmetros

  • tabId

    número opcional

    O ID da guia cujo status ativado você quer verificar.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (isEnabled: boolean) => void

    • isEnabled

      booleano

      Verdadeiro se a ação de extensão estiver ativada.

Retorna

  • Promise<boolean>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

openPopup()

Promessa Chrome 127+ 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

Abre o pop-up da extensão. Entre o Chrome 118 e o Chrome 126, isso só está disponível para extensões instaladas por política.

Parâmetros

  • opções

    OpenPopupOptions opcional

    Especifica opções para abrir o pop-up.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setBadgeBackgroundColor()

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

Define a cor de fundo do selo.

Parâmetros

  • detalhes

    objeto

    • cor

      string | ColorArray

      Uma matriz de quatro números inteiros no intervalo [0,255] que compõem a cor RGBA do selo. Por exemplo, o vermelho opaco é [255, 0, 0, 255]. Também pode ser uma string com um valor CSS, com vermelho opaco sendo #FF0000 ou #F00.

    • tabId

      número opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setBadgeText()

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

Define o texto do selo para a ação. O selo aparece acima do ícone.

Parâmetros

  • detalhes

    objeto

    • tabId

      número opcional

      Limita a mudança para 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á limpo. Se tabId for especificado e text for nulo, o texto da guia especificada será limpo e definido como padrão para o texto do selo global.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setBadgeTextColor()

Promessa Chrome 110 e mais recentes 
chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

Define a cor do texto do selo.

Parâmetros

  • detalhes

    objeto

    • cor

      string | ColorArray

      Uma matriz de quatro números inteiros no intervalo [0,255] que compõem a cor RGBA do selo. Por exemplo, o vermelho opaco é [255, 0, 0, 255]. Também pode ser uma string com um valor CSS, com vermelho opaco sendo #FF0000 ou #F00. Se esse valor não for definido, uma cor será escolhida automaticamente para contrastar com a cor de fundo do selo, deixando o texto visível. Cores com valores Alfa equivalentes a 0 não serão definidas e vão retornar um erro.

    • tabId

      número opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setIcon()

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

Define o ícone da ação. O ícone pode ser especificado como o caminho para um arquivo de imagem ou como os dados de pixel de um elemento de tela ou como o dicionário de um deles. É preciso especificar a propriedade path ou imageData.

Parâmetros

  • detalhes

    objeto

    • imageData

      ImageData | objeto opcional

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

    • tabId

      número opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    Chrome 96 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setPopup()

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

Define o documento HTML para ser aberto como um pop-up quando o usuário clica no ícone da ação.

Parâmetros

  • detalhes

    objeto

    • pop-up

      string

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

    • tabId

      número opcional

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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

setTitle()

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

Define o título da ação. Isso aparece na dica.

Parâmetros

  • detalhes

    objeto

    • tabId

      número opcional

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

    • título

      string

      A string que a ação precisa mostrar quando o mouse passa por cima.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

Eventos

onClicked

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

Disparado quando um ícone de ação é clicado. Esse evento não será acionado se a ação tiver um pop-up.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130 e versões mais recentes 
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

Acionada quando as configurações especificadas pelo usuário relacionadas à ação de uma extensão mudam.

Parâmetros