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 propriedades do objeto "commands" no manifesto da extensão.

A chave da propriedade é usada como o nome do comando. Os objetos de comando podem usar 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 usar um valor de string ou 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

String usada para fornecer ao usuário uma breve descrição da finalidade do comando. Essa string aparece na interface de gerenciamento de atalhos do 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 a partir da caixa de diálogo chrome://extensions/shortcuts.

Chaves com suporte

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

Chaves alfa

A... Z

Chaves numéricas

0... 9

Strings de tecla 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 de combinação 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, o Ctrl é convertido automaticamente em Command.

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

  • O uso da MacCtrl na combinação de outra plataforma causará um erro de validação e impedirá a instalação da extensão.

• O Shift é um modificador opcional em todas as plataformas.

• O Search é um modificador opcional exclusivo do ChromeOS.

• Certos atalhos do sistema operacional e do Chrome (por exemplo, gerenciamento de janelas) sempre têm prioridade sobre os atalhos de comando de extensões 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 seu 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 a ação do navegador, da página ou, respectivamente. Esses comandos não enviam eventos command.onCommand como comandos padrão.

Se você precisar realizar ações com base na abertura do pop-up, detecte um evento DOMContentLoaded no JavaScript do pop-up.

Escopo

Por padrão, o escopo dos comandos é definido 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 enquanto o Chrome não está em foco.

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

Os usuários finais podem remapear comandos globais para a combinação de teclas que preferirem 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 refletem 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 requer apenas uma declaração de comando no manifesto da extensão e um registro de listener, conforme 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 Uso, você também pode 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á está sendo usado por outra extensão, o atalho da segunda extensão não será registrado conforme esperado. Você pode fornecer uma experiência mais robusta para o usuário final antecipando essa possibilidade e verificando 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.
    }
  });
}

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

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