chrome.commands

Descripción

Manifest

Conceptos y uso

La API de Commands permite que los desarrolladores de extensiones definan comandos específicos y los vinculen 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 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 las plataformas.

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

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 la extensión. Las descripciones son obligatorias para los comandos estándar, 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 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. Si intentas cargar una extensión con una clave establecida en mayúsculas de forma incorrecta, se generará un error de análisis de manifiesto durante la 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 y Delete

Teclas de flecha: Up, Down, Left, Right

Claves de medios: MediaNextTrack, MediaPlayPause, MediaPrevTrack y MediaStop

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 o Alt.

  • Los modificadores no se pueden usar en combinación 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 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., la 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 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 mediante 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 comandos estándar.

Si necesitas tomar medidas según la apertura de la ventana emergente, considera detectar un evento 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á enfocado, las combinaciones de teclas de comandos están inactivas. A partir de Chrome 35, los desarrolladores de extensiones pueden marcar de manera opcional 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]. Esta es una medida de protección para minimizar el riesgo de anular las combinaciones de teclas en otras aplicaciones, ya que si, por ejemplo, Alt+P se permitiera 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 tienen la libertad de reasignar comandos globales a su combinación de teclas preferida usando 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 las combinaciones de teclas que el usuario puede invocar. En términos más básicos, 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 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 de la segunda extensión no se registrará como se espera. Puedes brindar una experiencia de usuario final más sólida si anticipas esta posibilidad y verificas si hay 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.
    }
  });
}

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

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