Descrição
Use a API chrome.action para controlar o ícone da extensão na barra de ferramentas do Google Chrome.
Disponibilidade
Manifesto
Para usar a API browser.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 ele não é incluído, a extensão ainda é mostrada na barra de ferramentas para fornecer acesso ao menu da extensão. Por isso, 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 extensão e é definido pela chave "default_icon" na
chave "action" do manifesto. Os ícones precisam ter 16 pixels independentes de 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 uma correspondência exata não for encontrada, 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 os dispositivos com fatores de escalonamento 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 definindo em um service worker 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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });
Para extensões compactadas (instaladas de um arquivo .crx), as imagens podem estar na maioria dos formatos que o mecanismo de renderização Blink pode exibir, incluindo PNG, JPEG, BMP, ICO e outros. O formato 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 ponteiro 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 padrão é definida usando o campo "default_title" da chave "action" em manifest.json.
Também é possível defini-lo de forma programática chamando action.setTitle().
Selo
As ações podem exibir um "ícone", que é um 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 fundo. Como o espaço é limitado, recomendamos que o texto do selo use quatro ou menos caracteres.
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.
browser.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: 'green'}, // Also, also green
() => { /* ... */ },
);
Pop-up
O pop-up de uma 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 se ajustar ao conteúdo. O tamanho do pop-up precisa estar entre 25 x 25 e 800 x 600 pixels.
O pop-up é definido inicialmente pela propriedade "default_popup" na chave "action" no arquivo
manifest.json. Se presente, essa propriedade precisa apontar para um caminho relativo no diretório
da 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 algo como:
function getTabId() { /* ... */}
function getTabBadge() { /* ... */}
browser.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
de forma programática para ser clicável. Se default_state for definido como "enabled" (o padrão),
a ação será ativada e clicável por padrão.
É possível controlar o estado de forma programática usando os métodos action.enable() e action.disable(). Isso só afeta se o pop-up (se houver) ou o evento action.onClicked é enviado
à extensão. Isso 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 extensão, declare o pop-up no manifest.json e especifique o
conteúdo que o Chrome precisa 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>
Injetar um script de conteúdo ao clicar
Um padrão comum para extensões é expor o recurso principal usando a ação da extensão. 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. Em seguida, o script de conteúdo exibe um alerta para verificar se tudo funcionou como 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
browser.action.onClicked.addListener((tab) => {
browser.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
browser.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
browser.action.disable();
// Clear all rules to ensure only our expected rules are set
browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new browser.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
browser.declarativeContent.onPageChanged.addRules(rules);
});
});
Tipos
OpenPopupOptions
Propriedades
-
windowId
número optional
O ID da janela em que o pop-up de ação será aberto. Se não for especificada, o padrão será a janela ativa no momento.
TabDetails
Propriedades
-
tabId
número optional
O ID da guia para consultar o estado. Se nenhuma guia for especificada, o estado não específico da guia será retornado.
UserSettings
A coleção de configurações especificadas pelo usuário relacionadas à ação de uma extensão.
Propriedades
-
isOnToolbar
booleano
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
Propriedades
-
isOnToolbar
booleano opcional
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()
browser.action.disable(
tabId?: number,
): Promise<void>
Desativa a ação de uma guia.
Parâmetros
-
tabId
número optional
O ID da guia em que você quer modificar a ação.
Retorna
-
Promessa<void>
enable()
browser.action.enable(
tabId?: number,
): Promise<void>
Ativa a ação para uma guia. Por padrão, as ações estão ativadas.
Parâmetros
-
tabId
número optional
O ID da guia em que você quer modificar a ação.
Retorna
-
Promessa<void>
getBadgeBackgroundColor()
browser.action.getBadgeBackgroundColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
Recebe a cor de fundo da ação.
Parâmetros
-
detalhes
Retorna
-
Promise<extensionTypes.ColorArray>
getBadgeText()
browser.action.getBadgeText(
details: TabDetails,
): Promise<string>
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 preenchimento 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
Retorna
-
Promise<string>
getBadgeTextColor()
browser.action.getBadgeTextColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
Recebe a cor do texto da ação.
Parâmetros
-
detalhes
Retorna
-
Promise<extensionTypes.ColorArray>
getPopup()
browser.action.getPopup(
details: TabDetails,
): Promise<string>
Recebe o documento HTML definido como o pop-up para essa ação.
Parâmetros
-
detalhes
Retorna
-
Promise<string>
Parâmetros
-
detalhes
Retorna
-
Promise<string>
getUserSettings()
browser.action.getUserSettings(): Promise<UserSettings>
Retorna as configurações especificadas pelo usuário relacionadas à ação de uma extensão.
Retorna
-
Promise<UserSettings>
isEnabled()
browser.action.isEnabled(
tabId?: number,
): Promise<boolean>
Indica se a ação da 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 optional
O ID da guia para verificar o status de ativação.
Retorna
-
Promise<boolean>
openPopup()
browser.action.openPopup(
options?: OpenPopupOptions,
): Promise<void>
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.
Retorna
-
Promessa<void>
setBadgeBackgroundColor()
browser.action.setBadgeBackgroundColor(
details: object,
): Promise<void>
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 [0,255] que compõem a cor RGBA do selo. Por exemplo, vermelho opaco é
[255, 0, 0, 255]. Também pode ser uma string com um valor CSS, em que o vermelho opaco é#FF0000ou#F00. -
tabId
número optional
Limita a mudança para quando uma guia específica é selecionada. É redefinida automaticamente quando a guia é fechada.
-
Retorna
-
Promessa<void>
setBadgeText()
browser.action.setBadgeText(
details: object,
): Promise<void>
Define o texto do selo para a ação. O selo é exibido na parte de cima do ícone.
Parâmetros
-
detalhes
objeto
-
tabId
número optional
Limita a mudança para quando uma guia específica é 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. SetabIdfor especificado etextfor nulo, o texto da guia especificada será apagado e o padrão será o texto do selo global.
-
Retorna
-
Promessa<void>
setBadgeTextColor()
browser.action.setBadgeTextColor(
details: object,
): Promise<void>
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, vermelho opaco é
[255, 0, 0, 255]. Também pode ser uma string com um valor CSS, em que o vermelho opaco é#FF0000ou#F00. Se você não definir esse valor, uma cor será escolhida automaticamente para contrastar com a cor de fundo do selo, de modo que o texto fique visível. As cores com valores Alfa equivalentes a 0 não serão definidas e vão retornar um erro. -
tabId
número optional
Limita a mudança para quando uma guia específica é selecionada. É redefinida automaticamente quando a guia é fechada.
-
Retorna
-
Promessa<void>
setIcon()
browser.action.setIcon(
details: object,
): Promise<void>
Define o ícone da ação. 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 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 real a ser 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, a 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 o ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem real a ser 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, a 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 optional
Limita a mudança para quando uma guia específica é selecionada. É redefinida automaticamente quando a guia é fechada.
-
Retorna
-
Promessa<void>
Chrome 96+ browser.* desde o Chrome 148
setPopup()
browser.action.setPopup(
details: object,
): Promise<void>
Define o documento HTML que será aberto como um pop-up quando o usuário clicar no ícone da ação.
Parâmetros
-
detalhes
objeto
-
pop-up
string
O caminho relativo para o arquivo HTML que será mostrado em um pop-up. Se definido como uma string vazia (
''), nenhum pop-up será mostrado. -
tabId
número optional
Limita a mudança para quando uma guia específica é selecionada. É redefinida automaticamente quando a guia é fechada.
-
Retorna
-
Promessa<void>
setTitle()
browser.action.setTitle(
details: object,
): Promise<void>
Define o título da ação. Isso aparece na dica.
Parâmetros
-
detalhes
objeto
-
tabId
número optional
Limita a mudança para quando uma guia específica é selecionada. É redefinida automaticamente quando a guia é fechada.
-
título
string
A string que a ação deve exibir quando o mouse é passado sobre ela.
-
Retorna
-
Promessa<void>
Eventos
onClicked
browser.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é semelhante a:(tab: tabs.Tab) => void
-
tab
-
onUserSettingsChanged
browser.action.onUserSettingsChanged.addListener(
callback: function,
)
Disparado quando as configurações especificadas pelo usuário relacionadas à ação de uma extensão mudam.
Parâmetros
-
callback
função
O parâmetro
callbacké semelhante a:(change: UserSettingsChange) => void
-
alterar
-