chrome.commands

Descripción

Manifiesto

Conceptos y uso

La API de Commands permite a los desarrolladores de extensiones definir comandos específicos y vincularlos a una combinación de teclas predeterminada. Cada comando que acepta una extensión debe declararse como propiedad 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 tomar dos propiedades.

suggested_key

Es una propiedad opcional que declara combinaciones de teclas predeterminadas para el comando. Si se omite, el comando no se vinculará. Esta propiedad puede tomar un valor de cadena o de objeto.

• Un valor de cadena especifica la combinación de teclas predeterminada que se debe usar en todas las plataformas.

• Un valor de objeto permite que el desarrollador de la extensión personalice el atajo de teclado para cada plataforma. Cuando proporciones accesos directos específicos de la plataforma, las propiedades de objeto válidas son default, chromeos, linux, mac y windows.

Consulta los requisitos de combinación de teclas para obtener más detalles.

description

Es una cadena que se usa para proporcionar al usuario una breve descripción del propósito del comando. Esta cadena aparece en la IU de administración de combinaciones de teclas de la extensión. 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 atajos de teclado sugeridos. 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 entre mayúsculas y minúsculas. Si intentas cargar una extensión con una clave con mayúsculas o minúsculas incorrectas, se producirá un error de análisis del manifiesto durante la instalación.

Claves alfa

A … Z

Teclas numéricas

0 … 9

Cadenas de claves estándar

General: Comma, Period, Home, End, PageUp, PageDown, Space, Insert, Delete

Teclas de flecha: Up, Down, Left, Right

Teclas de medios: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Cadenas de teclas modificadoras

Ctrl, Alt, Shift, MacCtrl (solo en macOS), Command (solo en macOS), Search (solo en ChromeOS)

Requisitos de combinación de teclas

• Los atajos de comandos de extensión deben incluir Ctrl o Alt.

  • Los modificadores no se pueden usar en combinación con las teclas multimedia.

  • En muchos teclados de macOS, Alt hace referencia a la tecla Option.

  • En macOS, también se puede usar Command o MacCtrl en lugar de Ctrl o Alt (consulta el siguiente viñeta).

• En macOS, Ctrl se convierte automáticamente en Command.

  • Command también se puede usar en el atajo "mac" para hacer referencia explícitamente a la tecla Comando.

  • Para usar la tecla Control en macOS, reemplaza Ctrl por MacCtrl cuando definas el atajo "mac".

  • Si usas MacCtrl en la combinación para 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.

• Algunas combinaciones de teclas del sistema operativo y de Chrome (p.ej., administración de ventanas) siempre tienen prioridad sobre las combinaciones de teclas de comandos de extensiones y no se pueden anular.

Cómo controlar eventos de comandos

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 tu service worker, puedes vincular un controlador a cada uno de los comandos definidos en el manifiesto con onCommand.addListener. 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 la acción de activar tu acción, la acción del navegador o la acción de la página, respectivamente. Estos comandos no envían eventos command.onCommand como los comandos estándar.

Si necesitas realizar alguna acción cuando se abra la ventana emergente, considera escuchar un evento DOMContentLoaded dentro del JavaScript de la ventana emergente.

Alcance

De forma predeterminada, los comandos se limitan al navegador Chrome. Esto significa que, cuando el navegador no está enfocado, los atajos de comandos están inactivos. A partir de Chrome 35, los desarrolladores de extensiones pueden marcar un comando como "global" de forma opcional. 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]. Esta es una medida de protección para minimizar el riesgo de anular combinaciones de teclas en otras aplicaciones, ya que, por ejemplo, si se permitiera Alt+P como global, es posible que la combinación de teclas para abrir un diálogo de impresión no funcione en otras aplicaciones.

Los usuarios finales pueden reasignar libremente los comandos globales a la combinación de teclas que prefieran 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

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 combinaciones de teclas que el usuario puede invocar. En su forma más básica, un comando solo requiere una declaración de comando en el manifiesto de la extensión y un registro 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 a la acción de una extensión. En el siguiente ejemplo, se inyecta 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 que los comandos estén 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((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(): Promise<Command[]>

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