chrome.commands

Descrição

Manifesto

Conceitos e uso

A API Commands permite que os desenvolvedores de extensões definam comandos específicos e os vinculem a uma combinação de teclas padrão. Cada comando aceito por uma extensão precisa ser declarado como propriedade do objeto "commands" no manifesto da extensão.

A chave da propriedade é usada como o nome do comando. Os objetos de comando podem ter duas propriedades.

suggested_key

Uma propriedade opcional que declara atalhos de teclado padrão para o comando. Se omitido, o comando não será vinculado. Essa propriedade pode receber uma string ou um valor de objeto.

• Um valor de string especifica o atalho de teclado padrão que deve ser usado em todas as plataformas.

• Um valor de objeto permite que o desenvolvedor de extensões personalize o atalho de teclado para cada plataforma. Ao fornecer atalhos específicos da plataforma, as propriedades de objeto válidas são default, chromeos, linux, mac e windows.

Consulte Requisitos de combinação de teclas para mais detalhes.

description

Uma string usada para fornecer ao usuário uma breve descrição da finalidade do comando. Essa string aparece na interface de gerenciamento de atalhos de teclado da extensão. As descrições são obrigatórias para comandos padrão, mas são ignoradas para comandos de ação.

Uma extensão pode ter muitos comandos, mas pode especificar no máximo quatro atalhos de teclado sugeridos. O usuário pode adicionar mais atalhos manualmente na caixa de diálogo chrome://extensions/shortcuts.

Chaves compatíveis

As seguintes teclas são atalhos de comando utilizáveis. As definições de chave diferenciam maiúsculas de minúsculas. Tentar carregar uma extensão com uma chave de caixa incorreta vai resultar em um erro de análise do manifesto no momento da instalação.

Chaves Alfa

A … Z

Teclas numéricas

0 … 9

Strings de chave padrão

Geral: Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Teclas de seta: Up, Down, Left, Right

Teclas de mídia: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Strings de teclas modificadoras

Ctrl, Alt, Shift, MacCtrl (somente macOS), Command (somente macOS), Search (somente ChromeOS)

Requisitos de combinação de teclas

• Os atalhos de comando de extensão precisam incluir Ctrl ou Alt.

  • Os modificadores não podem ser usados em combinação com as teclas de mídia.

  • Em muitos teclados macOS, Alt se refere à tecla Option.

  • No macOS, Command ou MacCtrl também podem ser usados no lugar de Ctrl ou Alt (confira o próximo item).

• No macOS, Ctrl é convertido automaticamente em Command.

  • Command também pode ser usado no atalho "mac" para se referir explicitamente à tecla Command.

  • Para usar a tecla Control no macOS, substitua Ctrl por MacCtrl ao definir o atalho "mac".

  • Usar MacCtrl na combinação para outra plataforma vai causar um erro de validação e impedir a instalação da extensão.

• Shift é um modificador opcional em todas as plataformas.

• Search é um modificador opcional exclusivo do ChromeOS.

• Alguns atalhos do sistema operacional e do Chrome (por exemplo, gerenciamento de janelas) sempre têm prioridade sobre atalhos de comando de extensão e não podem ser substituídos.

Processar eventos de comando

manifest.json:

{   "name": "My extension",   ...   "commands": {     "run-foo": {       "suggested_key": {         "default": "Ctrl+Shift+Y",         "mac": "Command+Shift+Y"       },       "description": "Run \"foo\" on the current page."     },     "_execute_action": {       "suggested_key": {         "windows": "Ctrl+Shift+Y",         "mac": "Command+Shift+Y",         "chromeos": "Ctrl+Shift+U",         "linux": "Ctrl+Shift+J"       }     }   },   ... } 

No service worker, é possível vincular um gerenciador a cada um dos comandos definidos no manifesto usando onCommand.addListener. Exemplo:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {   console.log(`Command: ${command}`); }); 

Comandos de ação

Os comandos _execute_action (Manifest V3), _execute_browser_action (Manifest V2) e _execute_page_action (Manifest V2) são reservados para a ação de acionar sua ação, ação do navegador ou ação da página, respectivamente. Esses comandos não enviam eventos command.onCommand como os comandos padrão.

Se você precisar realizar uma ação com base na abertura do pop-up, considere ouvir um evento DOMContentLoaded no JavaScript do pop-up.

Escopo

Por padrão, os comandos são definidos para o navegador Chrome. Isso significa que, quando o navegador não está em foco, os atalhos de comando ficam inativos. A partir do Chrome 35, os desenvolvedores de extensões podem marcar um comando como "global". Os comandos globais também funcionam quando o Chrome não está em foco.

As sugestões de atalhos de teclado para comandos globais são limitadas a Ctrl+Shift+[0..9]. Essa é uma medida de proteção para minimizar o risco de substituir atalhos em outros aplicativos. Por exemplo, se Alt+P fosse permitido como global, o atalho de teclado para abrir uma caixa de diálogo de impressão poderia não funcionar em outros aplicativos.

Os usuários finais podem remapear comandos globais para a combinação de teclas preferida usando a interface exposta em chrome://extensions/shortcuts.

Exemplo:

manifest.json:

{   "name": "My extension",   ...   "commands": {     "toggle-feature-foo": {       "suggested_key": {         "default": "Ctrl+Shift+5"       },       "description": "Toggle feature foo",       "global": true     }   },   ... } 

Exemplos

Os exemplos a seguir mostram a funcionalidade principal da API Commands.

Comando básico

Os comandos permitem que as extensões mapeiem a lógica para atalhos de teclado que podem ser invocados pelo usuário. Na forma mais básica, um comando só exige uma declaração no manifesto da extensão e um registro de listener, como mostrado no exemplo a seguir.

manifest.json:

{   "name": "Command demo - basic",   "version": "1.0",   "manifest_version": 3,   "background": {     "service_worker": "service-worker.js"   },   "commands": {     "inject-script": {       "suggested_key": "Ctrl+Shift+Y",       "description": "Inject a script on the page"     }   } } 

service-worker.js:

chrome.commands.onCommand.addListener((command) => {   console.log(`Command "${command}" triggered`); }); 

Comando de ação

Conforme descrito na seção Conceitos e uso, também é possível mapear um comando para uma ação de extensão. O exemplo a seguir injeta um script de conteúdo que mostra um alerta na página atual quando o usuário clica na ação da extensão ou aciona o atalho de teclado.

manifest.json:

{   "name": "Commands demo - action invocation",   "version": "1.0",   "manifest_version": 3,   "background": {     "service_worker": "service-worker.js"   },   "permissions": ["activeTab", "scripting"],   "action": {},   "commands": {     "_execute_action": {       "suggested_key": {         "default": "Ctrl+U",         "mac": "Command+U"       }     }   } } 

service-worker.js:

chrome.action.onClicked.addListener((tab) => {   chrome.scripting.executeScript({     target: {tabId: tab.id},     func: contentScriptFunc,     args: ['action'],   }); });  function contentScriptFunc(name) {   alert(`"${name}" executed`); }  // This callback WILL NOT be called for "_execute_action" chrome.commands.onCommand.addListener((command) => {   console.log(`Command "${command}" called`); }); 

Verificar comandos registrados

Se uma extensão tentar registrar um atalho que já está sendo usado por outra, o atalho da segunda extensão não será registrado como esperado. Você pode oferecer uma experiência mais robusta ao usuário final antecipando essa possibilidade e verificando colisões no momento da instalação.

service-worker.js:

chrome.runtime.onInstalled.addListener((details) => {   if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {     checkCommandShortcuts();   } });  // Only use this function during the initial install phase. After // installation the user may have intentionally unassigned commands. function checkCommandShortcuts() {   chrome.commands.getAll((commands) => {     let missingShortcuts = [];      for (let {name, shortcut} of commands) {       if (shortcut === '') {         missingShortcuts.push(name);       }     }      if (missingShortcuts.length > 0) {       // Update the extension UI to inform the user that one or more       // commands are currently unassigned.     }   }); } 

chrome.commands.getAll(): Promise<Command[]>

chrome.commands.onCommand.addListener(
  callback: function,
)