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
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
ewindows
.
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
eDelete
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
ouAlt
.- Modificadores não podem ser usados em combinação com teclas de mídia.
No macOS, o
Ctrl
é convertido automaticamente emCommand
.Para usar a tecla Control no macOS, substitua
Ctrl
porMacCtrl
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ã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 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((reason) => {
if (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 da extensão
-
name
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()
chrome.commands.getAll(
callback?: function,
)
Retorna todos os comandos de extensão registrados para esta extensão e os respectivos atalhos (se ativos). Antes do Chrome 110, esse comando não retornava _execute_action
.
Parâmetros
Retorna
-
Promessa<Command[]>
Chrome 96 ou mais recentePromessas são compatíveis apenas com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.