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.
Manifiesto
Conceptos y uso
La API de Commands permite que los desarrolladores de extensiones definan comandos específicos y los vinculen a un
combinación de teclas. Cada comando que acepte una extensión debe declararse como propiedad del
El 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 tomar dos propiedades.
suggested_key
Una propiedad opcional que declara las combinaciones de teclas predeterminadas para el comando. Si se omite, el comando se desvinculará. Esta propiedad puede tomar una cadena o un valor de objeto.
Un valor de cadena especifica la combinación de teclas predeterminada que debe usarse en todas y plataformas de Google Cloud.
Un valor de objeto permite que el desarrollador de la extensión personalice la combinación de teclas para cada plataforma. Cuando se proporcionan accesos directos específicos de la plataforma, las propiedades válidas del objeto son
default
.chromeos
,linux
,mac
ywindows
.
Consulta los Requisitos de la combinación de teclas para obtener más detalles.
description
Es una cadena que se usa para proporcionarle 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. Se requieren descripciones para los estándares pero se ignoran en el caso de los comandos de acción.
Una extensión puede tener muchos comandos, pero puede especificar como máximo cuatro combinaciones de teclas sugeridas. El
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 que se pueden usar. Las definiciones de clave distinguen mayúsculas de minúsculas. Intentando cargar una extensión con una clave mal escrita en mayúsculas y minúsculas provocará un error de análisis de manifiesto en durante el tiempo de instalación.
- Claves alfa
A
...Z
- Claves numéricas
0
...9
- Cadenas de clave estándar
General:
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
yDelete
Teclas de flecha:
Up
,Down
,Left
,Right
Claves de medios:
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
yMediaStop
- Cadenas de teclas modificadoras
Ctrl
,Alt
(Option
en macOS),Shift
,MacCtrl
(solo para macOS),Command
(solo para macOS),Search
(solo para ChromeOS)
Requisitos de la combinación de claves
Las combinaciones de teclas de los comandos de extensiones deben incluir
Ctrl
oAlt
.- Los modificadores no se pueden usar en combinación con las teclas multimedia.
En macOS,
Ctrl
se convierte automáticamente enCommand
.Para usar la tecla Control en macOS, reemplaza
Ctrl
porMacCtrl
cuando definas"mac"
. atajo.Si usas
MacCtrl
en combinación con otra plataforma, se producirá un error de validación y no se podrá instalar la extensión.
Shift
es un modificador opcional en todas las plataformas.Search
es un modificador opcional exclusivo de ChromeOS.Ciertas combinaciones de teclas del sistema operativo y de Chrome (p.ej., la administración de ventanas) siempre tienen prioridad sobre Combinaciones de teclas de comandos de extensión y no se pueden anular.
Cómo controlar 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 vincular un controlador a cada uno de los comandos definidos en el manifiesto
usando onCommand.addListener
. Por ejemplo:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
Comandos de acción
Se incluyen _execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) y
Los comandos _execute_page_action
(Manifest V2) están reservados para la acción de activar tu acción.
acción del navegador o de página, respectivamente. Estos comandos no envían
command.onCommand como comandos estándar.
Si necesitas realizar alguna acción en función de la apertura de la ventana emergente, considera escuchar un DOMContentLoaded en el JavaScript de la ventana emergente.
Alcance
De forma predeterminada, el alcance de los comandos se define en el navegador Chrome. Esto significa que, cuando el navegador no están enfocados, las combinaciones de teclas de comandos están inactivas. A partir de Chrome 35, los desarrolladores de extensiones pueden de manera opcional, marca un comando como “global”. Los comandos globales también funcionan cuando Chrome no está enfocado.
Las sugerencias de combinaciones de teclas para comandos globales se limitan a Ctrl+Shift+[0..9]
. Este es un
medidas de protección para minimizar el riesgo de anular los accesos directos en otras aplicaciones, ya que si, por
Por ejemplo, Alt+P
se permitía como global, la combinación de teclas para abrir un diálogo de impresión.
podrían no funcionar en otras aplicaciones.
Los usuarios finales tienen la libertad de reasignar comandos globales a su combinación de teclas preferida usando la IU expuesta.
a las 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
En los siguientes ejemplos, se muestra la funcionalidad principal de la API de Commands.
Comando básico
Los comandos permiten que las extensiones asignen lógica a las combinaciones de teclas que el usuario puede invocar. En su (más básico, un comando solo requiere una declaración de comando en el manifiesto de la extensión y un objeto 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 Conceptos y uso, también puedes asignar un comando al directorio acción. En el siguiente ejemplo, se inserta una secuencia de comandos de contenido que muestra un alerta en la página actual cuando el usuario hace clic en la acción de la extensión o activa 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 acceso directo que ya usa otra extensión, el de la segunda extensión no se registrará como se espera. Puedes proporcionar un perfil de usuario final al anticipar esta posibilidad y comprobar que no haya colisiones en el momento de la instalación.
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
Propiedades
-
descripción
string opcional
La descripción del comando de extensión
-
nombre
string opcional
El nombre del comando Extension
-
atajo
string opcional
El acceso directo activo para este comando o en blanco si no está activo.
Métodos
getAll()
chrome.commands.getAll(
callback?: function,
)
Muestra todos los comandos de extensión registrados para esta extensión y su combinación de teclas (si está activa). En versiones anteriores a 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
-
comandos
-
Muestra
-
Promesa<Command[]>
Chrome 96 y versiones posterioresLas promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El se resuelve con el mismo tipo que se pasa a la devolución de llamada.
Eventos
onCommand
chrome.commands.onCommand.addListener(
callback: function,
)
Se activa cuando un comando registrado se activa con una combinación de teclas.