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 chrome.action
, especifique um "manifest_version"
de 3
e inclua
a chave "action"
no seu 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"
e as filhas dela são opcionais. Quando não é incluída, sua extensão continua sendo exibida na barra de ferramentas para dar acesso ao menu da extensão. 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 tecla "default_icon"
na
a 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 imagens. O Chrome usa estes ícones
para escolher qual escala de imagem usar. Se uma correspondência exata não for encontrada, o Chrome selecionará a opção mais próxima
disponível e a dimensiona para se ajustar à imagem, o que pode afetar a qualidade dela.
Os dispositivos com fatores de escala menos comuns, como 1,5x ou 1,2x estão se tornando mais
comum, recomendamos que você forneça vários tamanhos para os ícones. Isso também
protege sua extensão contra possíveis mudanças no tamanho de exibição dos ícones para o futuro. No entanto,
se você fornecer apenas um tamanho, a chave "default_icon"
também poderá ser definida como um
string com o caminho para um único ícone em vez de um dicionário.
Você também pode chamar action.setIcon()
para definir o ícone da sua extensão de forma programática.
especificando um caminho de imagem diferente ou fornecendo um ícone gerado dinamicamente usando a tela HTML
elemento, ou, se for definido por um service worker de extensão, o elemento fora da tela
API canvas.
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 compactadas (instaladas a partir de um arquivo .crx), as imagens podem estar na maioria dos formatos nos quais o Blink de processamento de vídeo pode exibir, incluindo PNG, JPEG, BMP, ICO, entre outros. O SVG não é compatível. As extensões descompactadas devem usar imagens PNG.
Dica (título)
A dica, ou título, aparece quando o usuário mantém o ponteiro do mouse sobre o ícone da extensão no barra de ferramentas. Também é incluído no texto acessível falado pelos leitores de tela quando o botão é foco.
A dica padrão é definida usando o campo "default_title"
da chave "action"
em manifest.json
.
Também é possível defini-la de maneira programática chamando action.setTitle()
.
Selo
Opcionalmente, as ações podem exibir um "selo" — um pouco de texto sobre o ícone. Isso permite que você atualize a ação para exibir 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. Valores de cor do selo
pode ser uma matriz de quatro números inteiros entre 0 e 255 que compõem a cor RGBA do
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
() => { /* ... */ },
);
Pop-up
O pop-up de uma ação é exibido 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 o conteúdo dela. O tamanho do pop-up deve ser entre 25 x 25 e 800 x 600 pixels.
O pop-up é inicialmente definido pela propriedade "default_popup"
na chave "action"
na
arquivo manifest.json
. Se presente, esta propriedade precisa apontar para um caminho relativo dentro da extensão
diretório. 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 da extensão podem ter estados diferentes para cada guia. Para definir um valor para uma pessoa
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() { /* ... */}
chrome.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
Se a propriedade tabId
for deixada de fora, a configuração será tratada como global. Específico de guia
têm prioridade sobre as globais.
Estado ativado
Por padrão, as ações da barra de ferramentas estão ativadas (clicáveis) em todas as guias. Você pode controlar isso usando o
métodos action.enable()
e action.disable()
. Isso afeta apenas se o pop-up (se houver) ou
action.onClicked
evento é enviado para sua 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 uso das ações em extensões. Para testar a API, instale o exemplo da API Action das chrome-extension-samples repositório de dados.
Mostrar um pop-up
É comum que uma extensão exiba um pop-up quando o usuário clicar na ação da extensão. Para
implemente isso na sua extensão, declare o pop-up no manifest.json
e especifique o
conteúdo que o Chrome deve exibir na janela 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 as extensões é expor o recurso principal usando o à ação. O exemplo a seguir 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 que 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
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 de 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
Propriedades
-
windowId
número opcional
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 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.
UserSettings
O conjunto 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 nas janelas do navegador barra de ferramentas de nível superior (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 nas janelas do navegador barra de ferramentas de nível superior (ou seja, se a extensão foi "fixada" pelo usuário).
Métodos
disable()
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 esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Ativa a ação para uma guia. As ações estão ativadas por padrão.
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 esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Recebe a cor de fundo da ação.
Parâmetros
-
detalhes
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(result: ColorArray) => void
-
resultado
-
Retorna
-
Promise<browserAction.ColorArray>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getBadgeText()
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 um texto de selo específico da guia tenha sido fornecido.
Parâmetros
-
detalhes
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Recebe a cor do texto da ação.
Parâmetros
-
detalhes
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(result: ColorArray) => void
-
resultado
-
Retorna
-
Promise<browserAction.ColorArray>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Extrai o documento HTML definido como o pop-up para esta ação.
Parâmetros
-
detalhes
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Recebe o título da ação.
Parâmetros
-
detalhes
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(result: string) => void
-
resultado
string
-
Retorna
-
Promessa<string>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
getUserSettings()
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 esta aparência:(userSettings: UserSettings) => void
-
userSettings
-
Retorna
-
Promise<UserSettings>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
isEnabled()
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). Ações ativadas usando apenas declarativeContent
sempre retornam "false".
Parâmetros
-
tabId
número opcional
O ID da guia cujo status você quer verificar.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:(isEnabled: boolean) => void
-
isEnabled
booleano
Verdadeiro se a ação de extensão estiver ativada.
-
Retorna
-
Promise<boolean>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Abre o pop-up da extensão. Entre o Chrome 118 e o 126, isso só está disponível para extensões instaladas pela política.
Parâmetros
-
opções
OpenPopupOptions opcional
Especifica as opções para abrir o pop-up.
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setBadgeBackgroundColor()
chrome.action.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 [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, sendo que o vermelho opaco é#FF0000
ou#F00
. -
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>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Define o texto do selo para a ação. 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. 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 opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setBadgeTextColor()
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, vermelho opaco é
[255, 0, 0, 255]
. Também pode ser uma string com um valor CSS, sendo que o vermelho opaco é#FF0000
ou#F00
. Se esse valor não for definido, uma cor será escolhida automaticamente, o que vai contrastar com a cor de fundo do selo, fazendo com que o texto fique visível. Cores com valores alfa equivalentes a 0 não serão definidas e retornarão um erro. -
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>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setIcon()
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, como os dados de pixel de um elemento de tela ou como um dicionário de qualquer 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 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
, 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 -> caminho da imagem relativa} apontando para o ícone a ser definido. Se o ícone for especificado como um dicionário, a imagem real a ser 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
, 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 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 96 ou versão mais recenteO Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
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 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
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
setTitle()
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 quando uma guia específica é selecionada. É redefinido automaticamente quando a guia é fechada.
-
título
string
A string que a ação deve exibir ao passar o mouse.
-
-
callback
função opcional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promessa<void>
O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.
Eventos
onClicked
chrome.action.onClicked.addListener(
callback: function,
)
Disparado quando um ícone de ação é clicado. Este evento não será disparado se a ação tiver um pop-up.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(tab: tabs.Tab) => void
-
tab
-
onUserSettingsChanged
chrome.action.onUserSettingsChanged.addListener(
callback: function,
)
Disparado quando as configurações especificadas pelo usuário relacionadas à mudança de ação de uma extensão.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(change: UserSettingsChange) => void
-
alterar
-