chrome.commands

Descrição

Use a API de comandos para adicionar atalhos de teclado que acionam ações na sua extensão, por exemplo, uma ação para abrir a ação do navegador ou enviar um comando para a extensão.

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"commands"

Conceitos e uso

A API Commands permite que os desenvolvedores de extensões definam comandos específicos e os vinculem a uma combinação padrão de teclas. Cada comando aceito por uma extensão precisa ser declarado como propriedades 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 será desvinculado. Essa propriedade pode receber uma string ou um valor de objeto.

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

  • Um valor de objeto permite que o desenvolvedor da extensão 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 os requisitos de combinação de chaves para mais detalhes.

description

Uma string usada para fornecer ao usuário uma breve descrição do objetivo 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 manualmente mais atalhos na caixa de diálogo chrome://extensions/shortcuts.

Chaves compatíveis

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

Chaves Alfa
A … Z
Chaves 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 da 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 (consulte o próximo ponto).

  • 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".

    • O uso de MacCtrl na combinação para outra plataforma causa um erro de validação e impede 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 os atalhos de comando da 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 worker do serviço, é 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 comandos padrão.

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

Escopo

Por padrão, os comandos são aplicados ao 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 substituição de atalhos em outros aplicativos. Se, por exemplo, 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. No nível mais básico, um comando só exige uma declaração de comando no manifesto da extensão e um registro de listener, conforme mostrado no exemplo abaixo.

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 a ação de uma 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á é usado por outra, o atalho da segunda extensão não será registrado como esperado. É possível oferecer uma experiência do usuário final mais robusta 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.
    }
  });
}

Tipos

Command

Propriedades

  • descrição

    string opcional

    A descrição do comando de extensão

  • nome

    string opcional

    O nome do comando de extensão

  • atalho

    string opcional

    O atalho ativo para esse comando ou em branco se não estiver ativo.

Métodos

getAll()

Promessa 
chrome.commands.getAll(
  callback?: function,
)

Retorna todos os comandos de extensão registrados para essa extensão e o atalho dela (se ativo). Antes do Chrome 110, esse comando não retornava _execute_action.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (commands: Command[]) => void

Retorna

  • Promise<Command[]>

    Chrome 96 e versões mais recentes

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os 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 transmitido para o callback.

Eventos

onCommand

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

É acionado quando um comando registrado é ativado usando um atalho de teclado.

Parâmetros

  • callback

    função

    O parâmetro callback tem este formato: 

    (command: string, tab?: tabs.Tab) => void