chrome.action

Descrição

Disponibilidade

Manifesto

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" (e os filhos dela) é opcional. Quando ele não está incluído, a extensão ainda é mostrada na barra de ferramentas para dar acesso ao menu dela. 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 opção mais próxima disponível e dimensioná-la para se ajustar à imagem, o que pode afetar a qualidade.

Como os 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 da 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.

Você também pode chamar action.setIcon() para definir o ícone da extensão de maneira programática especificando um caminho de imagem diferente ou fornecendo um ícone gerado dinamicamente usando o elemento canvas HTML ou, se a definição for feita por um service worker de extensão, a API canvas em segundo plano.

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 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 o foco.

A dica 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 "indicador", que é 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 use 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   () => { /* ... */ }, ); 

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" do 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 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 ficam ativadas (clicáveis) em todas as guias. Para mudar esse padrão, defina 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 estiver definido como "enabled" (o padrão), a ação será ativada e poderá ser clicada 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 para 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 no repositório chrome-extension-samples.

Mostrar um pop-up

É comum uma extensão mostrar 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 deve 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 insere um script de conteúdo na página atual. Em seguida, 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 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);   }); }); 

chrome.action.disable(
  tabId?: number,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

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