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 um padrão combinação de teclas. Cada comando aceito por uma extensão deve ser declarado como propriedades do Objeto "commands" no manifesto da extensão.

A chave de 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 será desvinculado. Essa propriedade pode assumir uma string ou um valor de objeto.

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

  • Um valor de objeto permite que o desenvolvedor da extensão personalize o atalho de teclado para cada de 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 saber mais detalhes.

description

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 o mas são ignorados para comandos de ação.

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

Chaves compatíveis

As teclas a seguir são atalhos de comando utilizáveis. As principais definições diferenciam maiúsculas de minúsculas. Tentando carregar uma extensão com uma chave com maiúsculas e minúsculas incorretas resultará em um erro de análise do manifesto em tempo de instalação.

Teclas Alfa
A... Z
Chaves numéricas
0... 9
Strings de chave padrão

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

Teclas de seta: Up, Down, Left, Right

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

Strings de tecla modificadora

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

.

Requisitos para combinações de teclas

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

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

  • No macOS, Ctrl é convertido automaticamente em Command.

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

    • O uso de MacCtrl na combinação com outra plataforma vai causar um erro de validação e impedir que a extensão seja instalada.

  • Shift é um modificador opcional em todas as plataformas.

  • Search é um modificador opcional exclusivo do ChromeOS.

  • Certos sistemas operacionais e atalhos do Chrome (por exemplo, gerenciamento de janelas) sempre têm prioridade 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

O _execute_action (Manifesto V3), _execute_browser_action (Manifesto V2) e Os comandos _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 de pop-up, considere ouvir um evento DOMContentLoaded dentro do JavaScript do pop-up.

Escopo

Por padrão, os comandos têm como escopo o navegador Chrome. Isso significa que, quando o navegador não estiver em foco, os atalhos de comando ficarão inativos. A partir do Chrome 35, os desenvolvedores de extensões poderão também é possível marcar o comando como "global". Os comandos globais também funcionam enquanto o Chrome não está em foco.

As sugestões de atalhos de teclado para comandos globais estão limitadas a Ctrl+Shift+[0..9]. Esta é uma medida de proteção para minimizar o risco de substituir atalhos em outros aplicativos, já que se, por Por exemplo, Alt+P foram permitidos como globais, o atalho do teclado para abrir uma caixa de diálogo de impressão. pode não funcionar em outros aplicativos.

Os usuários finais podem remapear comandos globais para sua combinação de teclas preferida usando a interface exposta às 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(a) mais básico, um comando só exige uma declaração de comando no manifesto da extensão e um 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, você também pode mapear um comando para o à ação. O exemplo a seguir injeta um script de conteúdo que mostra uma na página atual quando o usuário clicar na ação da extensão ou acionar 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 extensão, a o atalho da segunda extensão não será registrado como esperado. É possível oferecer um conjunto de dados experiência ao antecipar essa possibilidade e verificar se há 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 este 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 esta extensão e seus atalhos (se ativos). Antes do Chrome 110, esse comando não retornava _execute_action.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (commands: Command[]) => void

Retorna

  • Promessa <Comando[]>

    Chrome 96 ou versão mais recente

    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

onCommand

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

Disparado quando um comando registrado é ativado usando um atalho de teclado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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