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

Es una propiedad opcional que declara combinaciones de teclas predeterminadas para el comando. Si se omite, el comando no estará vinculado. Esta propiedad puede aceptar una cadena o un valor 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 acceso directo del teclado para cada plataforma. Cuando proporcionas atajos específicos de la plataforma, las propiedades de objetos válidas son default, chromeos, linux, mac y windows.

Consulta los requisitos de combinación de claves 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 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 más atajos de forma manual 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 claves distinguen mayúsculas de minúsculas. Si intentas cargar una extensión con una clave con mayúsculas o minúsculas incorrectas, 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

Cadenas de claves estándar

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

Teclas de flecha: Up, Down, Left, Right

Teclas multimedia: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Cadenas de teclas modificadoras

Ctrl, Alt, Shift, MacCtrl (solo para macOS), Command (solo para macOS), Search (solo para 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 pueden usar Command o MacCtrl en lugar de Ctrl o Alt (consulta el siguiente punto).

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

  • Command también se puede usar en la combinación de teclas "mac" para hacer referencia explícitamente a la tecla Comando.

  • Para usar la tecla Control en macOS, reemplaza Ctrl por MacCtrl cuando definas la combinación de teclas "mac".

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

Controla 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 tu trabajador de servicio, 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 despachan eventos command.onCommand como los comandos estándar.

Si necesitas realizar acciones en función de la apertura de la ventana emergente, considera escuchar un evento DOMContentLoaded dentro del código JavaScript de la ventana emergente.

Alcance

De forma predeterminada, los comandos se aplican 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 los 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 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

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 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 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 el atajo 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`);
});

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.
    }
  });
}

chrome.commands.getAll(
  callback?: function,
)

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