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 os filhos dela são opcionais. Quando não estiver incluída, sua extensão ainda será exibida na barra de ferramentas para fornecer 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
Icon
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 de largura e altura independentes de dispositivo (DIPs).
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 selecionará a opção mais próxima disponível e a dimensionará 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 os ícones. Isso também protege sua extensão para possíveis mudanças no tamanho de exibição dos ícones.
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 em um service worker de extensão, a API
de 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 compactadas (instaladas de um arquivo .crx), as imagens podem estar na maioria dos formatos que o mecanismo de renderização 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 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"
no manifest.json
.
Você também pode defini-lo de maneira programática chamando action.setTitle()
.
Selo
Opcionalmente, as ações podem exibir um "selo", um pedaço 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 use quatro caracteres ou menos.
Para criar um selo, defina-o de maneira programática chamando action.setBadgeBackgroundColor()
e
action.setBadgeText()
. Não há uma configuração padrão de selo 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
() => { /* ... */ },
);
Pop-up
Um 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 se ajustar ao conteúdo. O tamanho do pop-up precisa ser de 25 x 25 a 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 dentro do 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 da extensão podem ter estados diferentes para cada guia. Se quiser definir o valor de uma guia específica, use a propriedade tabId
nos métodos de configuração da API action
. Por exemplo, para
definir o texto do selo para uma guia específica, faça algo parecido com isto:
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. As configurações específicas
de guias 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 controlar isso usando os
métodos action.enable()
e action.disable()
. Isso afeta apenas se o pop-up (se houver) ou
o evento action.onClicked
será enviado para sua extensão. Não afeta a presença da ação
na barra de ferramentas.
Exemplos
Os exemplos a seguir mostram algumas formas comuns de uso das ações em extensões. Para testar essa API, instale o exemplo da API Action no repositório chrome-extension-samples.
Mostrar um pop-up
É comum que uma extensão exiba um pop-up quando o usuário clica na ação da extensão. Para
implementar esse recurso na sua própria extensão, declare o pop-up na manifest.json
e especifique o
conteúdo que o Chrome precisa mostrar nele.
// 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 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. O script de conteúdo mostra 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
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 atualmente.
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.
UserSettings
O conjunto de configurações especificadas pelo usuário relacionadas à ação de uma extensão.
Propriedades
-
isOnToolbar
boolean
Se o ícone de ação da extensão está visível na barra de ferramentas do nível superior da janela do navegador (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 optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
enable()
chrome.action.enable(
tabId?: number,
callback?: function,
)
Ativa a ação para 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 optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getBadgeBackgroundColor()
chrome.action.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Recebe a cor de fundo da ação.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: ColorArray)=>void
-
resultado
-
Retorna
-
Promise<browserAction.ColorArray>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getBadgeText()
chrome.action.getBadgeText(
details: TabDetails,
callback?: function,
)
Recebe o texto do selo da ação. Se nenhuma guia for especificada, o texto do símbolo 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 o texto do selo específico da guia tenha sido fornecido.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string)=>void
-
resultado
string
-
Retorna
-
Promessa<string>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getBadgeTextColor()
chrome.action.getBadgeTextColor(
details: TabDetails,
callback?: function,
)
Recebe a cor do texto da ação.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: ColorArray)=>void
-
resultado
-
Retorna
-
Promise<browserAction.ColorArray>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getPopup()
chrome.action.getPopup(
details: TabDetails,
callback?: function,
)
Recebe o conjunto de documentos html como o pop-up para essa ação.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string)=>void
-
resultado
string
-
Retorna
-
Promessa<string>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
getTitle()
chrome.action.getTitle(
details: TabDetails,
callback?: function,
)
Recebe o título da ação.
Parâmetros
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:(result: string)=>void
-
resultado
string
-
Retorna
-
Promessa<string>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
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 optional
O parâmetro
callback
tem esta aparência:(userSettings: UserSettings)=>void
-
userSettings
-
Retorna
-
Promise<UserSettings>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
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). As ações ativadas usando apenas declarativeContent
sempre retornam "false".
Parâmetros
-
tabId
número opcional
O ID da guia com o status de ativação que você quer verificar.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(isEnabled: boolean)=>void
-
isEnabled
boolean
Verdadeiro se a ação de extensão estiver ativada.
-
Retorna
-
Promise<boolean>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
openPopup()
chrome.action.openPopup(
options?: OpenPopupOptions,
callback?: function,
)
Abre o pop-up da extensão.
Parâmetros
-
opções
OpenPopupOptions opcional
Especifica as opções para abrir o pop-up.
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
setBadgeBackgroundColor()
chrome.action.setBadgeBackgroundColor(
details: object,
callback?: function,
)
Define a cor de 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, o vermelho opaco é
[255, 0, 0, 255]
. Também pode ser uma string com um valor CSS, com o vermelho opaco sendo#FF0000
ou#F00
. -
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>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
setBadgeText()
chrome.action.setBadgeText(
details: object,
callback?: function,
)
Define o texto do selo para a ação. 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 quantidade de caracteres pode ser transmitida, 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
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
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, o vermelho opaco é
[255, 0, 0, 255]
. Também pode ser uma string com um valor CSS, com o vermelho opaco sendo#FF0000
ou#F00
. Se esse valor não for definido, uma cor que vai contrastar com o plano de fundo do selo será escolhida automaticamente e o texto ficará visível. As 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 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>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
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 ou como os dados de pixel de um elemento de tela ou como um dicionário de qualquer um desses itens. É preciso especificar a propriedade path ou imageData.
Parâmetros
-
detalhes
objeto
-
imageData
ImageData|object 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 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 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
setPopup()
chrome.action.setPopup(
details: object,
callback?: function,
)
Define o documento HTML para 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 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
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.
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 a quando uma determinada guia é selecionada. É redefinida automaticamente quando a guia é fechada.
-
título
string
É a string que a ação deve exibir ao passar o mouse sobre ela.
-
-
callback
função optional
O parâmetro
callback
tem esta aparência:()=>void
Retorna
-
Promise<void>
Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas 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 que é passado para o callback.