chrome.commands

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

Para usar esta API, se deben declarar las siguientes claves en el manifiesto.

"commands"

Conceptos y 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 y windows.

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 y Delete

Teclas de flecha: Up, Down, Left y Right

Claves de contenido multimedia: MediaNextTrack, MediaPlayPause, MediaPrevTrack y MediaStop

Cadenas de teclas modificadoras

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

Nota: Se quitó Tab de la lista de teclas compatibles en Chrome 33 por motivos de accesibilidad.

Requisitos de las combinaciones de teclas

• Las combinaciones de teclas de comandos de extensiones deben incluir Ctrl o Alt.

  • Los modificadores no se pueden usar junto con las teclas multimedia.

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

  • Para usar la tecla Control en macOS, reemplaza Ctrl por MacCtrl 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.

Nota: Para evitar conflictos con la tecla AltGr, no se permiten combinaciones de teclas que involucren Ctrl+Alt.

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

Nota: ChromeOS no es compatible con los comandos globales.

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((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

  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()

Promesa

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

    Comando

Devuelve

• Promesa<Comando[]>

  Chrome 96 y versiones posteriores

  Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa 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.

Parámetros

• callback

  la función

  El parámetro callback se ve de la siguiente manera:

  (command: string,tab?: tabs.Tab)=>void

  • comando

    cadena

  • tab

    tabs.Tab opcional