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 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 comando 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 precisa ser usado em todas as plataformas.

• Um valor de objeto permite que o desenvolvedor da extensão personalize o atalho do 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 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 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 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. A tentativa de carregar uma extensão com uma chave com maiúsculas e minúsculas incorretamente resultará em um erro de análise do manifesto no momento da 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 atalho "mac".

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

• 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 expedem 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 têm como escopo 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 de 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 de 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 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 parte mais básica, um comando exige 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, o atalho da segunda extensão não será registrado como esperado. Você pode oferecer uma experiência do usuário final mais robusta 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.
    }
  });
}

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

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