Descripción
Usa la API de comandos para agregar combinaciones de teclas que activen acciones en tu extensión, por ejemplo, una acción para abrir la acción del navegador o enviar un comando a la extensión.
Manifest
Uso
La API de Commands permite a los desarrolladores de extensiones definir comandos específicos y vincularlos a una combinación de claves
predeterminada. Cada comando que acepte una extensión debe declararse como propiedades del objeto
"commands"
en el manifiesto de la extensión.
La clave de propiedad se usa como el nombre del comando. Los objetos de comando pueden tener dos propiedades.
suggested_key
Una propiedad opcional que declara combinaciones de teclas predeterminadas para el comando. Si se omite, el comando no se vinculará. Esta propiedad puede tomar una cadena o un valor de objeto.
Un valor de string especifica la combinación de teclas predeterminada que se debe usar en todas las plataformas.
Un valor de objeto permite al desarrollador de extensiones personalizar la combinación de teclas para cada plataforma. Cuando proporcionas accesos directos específicos de la plataforma, las propiedades de objeto válidas son
default
,chromeos
,linux
,mac
ywindows
.
Consulta Requisitos de combinación de teclas para obtener detalles adicionales.
description
Es una cadena que se usa para proporcionar al usuario una descripción breve del propósito del comando. Esta cadena aparece en la IU de administración de combinaciones de teclas de extensiones. Las descripciones son obligatorias para los comandos estándar, pero se ignoran para los comandos de acción.
Una extensión puede tener muchos comandos, pero puede especificar como máximo cuatro combinaciones de teclas sugeridas. El usuario puede agregar manualmente más accesos directos desde el diálogo chrome://extensions/shortcuts
.
Claves admitidas
Las siguientes teclas son combinaciones de teclas de comandos utilizables. Las definiciones de claves distinguen mayúsculas de minúsculas. Si intentas cargar una extensión con una clave incorrecta, se generará un error de análisis de manifiesto en el momento de la instalación.
- Claves alfa
A
...Z
- Claves numéricas
0
...9
- Strings de teclas estándar
General:
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
yDelete
Teclas de flecha:
Up
,Down
,Left
yRight
Claves de contenido multimedia:
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
yMediaStop
- Cadenas de teclas modificadoras
Ctrl
,Alt
(Option
en macOS),Shift
,MacCtrl
(solo en macOS),Command
(solo en macOS),Search
(solo ChromeOS)
Requisitos de las combinaciones de teclas
Las combinaciones de teclas de comandos de extensiones deben incluir
Ctrl
oAlt
.- Los modificadores no se pueden usar junto con las teclas multimedia.
En macOS,
Ctrl
se convierte automáticamente enCommand
.Para usar la tecla Control en macOS, reemplaza
Ctrl
porMacCtrl
cuando definas la combinación de teclas"mac"
.Si usas
MacCtrl
en combinación con otra plataforma, se generará un error de validación y se impedirá que se instale la extensión.
Shift
es un modificador opcional en todas las plataformas.Search
es un modificador opcional exclusivo de ChromeOS.Algunas combinaciones de teclas del sistema operativo y de Chrome (p.ej., la administración de ventanas) siempre tienen prioridad sobre las combinaciones de teclas de comandos de extensiones y no se pueden reemplazar.
Cómo manejar 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"
}
}
},
...
}
En el service worker, puedes usar onCommand.addListener
para vincular un controlador a cada uno de los comandos definidos en el manifiesto. Por ejemplo:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
Comandos de acción
Los comandos _execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) y _execute_page_action
(Manifest V2) están reservados para los fines de activar tu acción, la acción del navegador o la acción de la página, respectivamente. Estos comandos no despachan eventos command.onCommand como los comandos estándar.
Si necesitas realizar alguna acción de acuerdo con la apertura de la ventana emergente, considera detectar un evento DOMContentLoaded en el código JavaScript de la ventana emergente.
Alcance
De forma predeterminada, el alcance de los comandos se limita al navegador Chrome. Esto significa que, cuando el navegador no tiene foco, las combinaciones de teclas de comandos están inactivas. A partir de Chrome 35, los desarrolladores de extensiones pueden marcar de forma opcional un comando como "global". Los comandos globales también funcionan mientras Chrome no está enfocado.
Las sugerencias de combinaciones de teclas para comandos globales se limitan a Ctrl+Shift+[0..9]
. Esta es una medida de protección para minimizar el riesgo de anular combinaciones de teclas en otras aplicaciones, ya que si, por ejemplo, se permitira Alt+P
como global, la combinación de teclas para abrir un diálogo de impresión podría no funcionar en otras aplicaciones.
Los usuarios finales tienen la libertad de reasignar los comandos globales a su combinación de teclas preferida con la IU expuesta en chrome://extensions/shortcuts
.
Ejemplo:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
Ejemplos
Los siguientes ejemplos reflejan la funcionalidad principal de la API de Commands.
Comando básico
Los comandos permiten que las extensiones asignen lógica a combinaciones de teclas que el usuario puede invocar. Básicamente, un comando solo requiere una declaración de comando en el manifiesto de la extensión y un registro de objetos de escucha, como se muestra en el siguiente ejemplo.
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 acción
Como se describe en la sección Uso, también puedes asignar un comando a la acción de una extensión. En el siguiente ejemplo, se inserta una secuencia de comandos de contenido que muestra una alerta en la página actual cuando el usuario hace clic en la acción de la extensión o activa la combinación de teclas.
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`);
});
Verifica los comandos registrados
Si una extensión intenta registrar un atajo que ya usa otra extensión, el atajo de la segunda extensión no se registrará como se espera. Puedes proporcionar una experiencia del usuario final más sólida si anticipas esta posibilidad y verificas si hay colisiones durante la instalación.
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
Propiedades
-
descripción
cadena opcional
La descripción del comando de la extensión
-
name
cadena opcional
El nombre del comando de la extensión
-
atajo
cadena opcional
La combinación de teclas activa para este comando o en blanco si no está activa.
Métodos
getAll()
chrome.commands.getAll(
callback?: function,
)
Muestra todos los comandos de extensión registrados para esta extensión y su acceso directo (si está activo). Antes de Chrome 110, este comando no mostraba _execute_action
.
Parámetros
-
callback
Función opcional
El parámetro
callback
se ve de la siguiente manera:(commands: Command[]) => void
-
commands
-
Devuelve
-
Promesa<Comando[]>
Chrome 96 y versiones posterioresLas promesas solo son compatibles con Manifest V3 y versiones posteriores; otras plataformas deben usar devoluciones de llamada.
Eventos
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Se activa cuando un comando registrado se activa con una combinación de teclas.