chrome.commands

refresh date: 2026-09-25 robots: noindex

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

Las siguientes claves se deben declarar en el manifiesto para usar esta API.

"commands"

Uso

La API de Commands permite que los desarrolladores de extensiones definan comandos específicos y los vinculen a una combinación de teclas predeterminada. Cada comando que acepta una extensión se debe declarar 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 las 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 la combinación de teclas para cada plataforma. Cuando se proporcionan 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 claves para obtener más detalles.

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 la extensión. Las descripciones son obligatorias para los comandos estándar, pero se ignoran en 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 más accesos directos 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 y minúsculas incorrectas, se producirá un error de análisis del manifiesto en el momento de 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 multimedia: MediaNextTrack, MediaPlayPause, MediaPrevTrack, MediaStop

Cadenas de teclas modificadoras

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

Requisitos de las combinaciones de teclas

  • Las combinaciones de teclas de los comandos de la extensión 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 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.

  • Ciertas 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 la extensión y no se pueden reemplazar.

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, acción del navegador o acción de la página, respectivamente. Estos comandos no envían eventos command.onCommand como los comandos estándar.

Si necesitas tomar medidas 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 limitan al navegador Chrome. Esto significa que, cuando el navegador no tiene el enfoque, 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, si, por ejemplo, se permitiera 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 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 las combinaciones de teclas que puede invocar el usuario. 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 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 una combinación de teclas que ya usa otra extensión, la combinación de teclas 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 en el momento de la instalación.

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (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 de extensión

  • Acceso directo

    string opcional

    Es el acceso directo activo para este comando o está en blanco si no está activo.

Métodos

getAll()

Promise 
chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

Muestra todos los comandos de extensión registrados para esta extensión y su combinación de teclas (si está activa). Antes de Chrome 110, este comando no devolvía _execute_action.

Parámetros

  • callback

    función opcional

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

    (commands: Command[]) => void

Muestra

  • Promise<Command[]>

    Chrome 96 y versiones posteriores

    Se resuelve con una lista de los comandos registrados.

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onCommand

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

Se activa cuando se ejecuta un comando registrado con una combinación de teclas.

Parámetros

  • callback

    función

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

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

    • comando

      string

    • tabulación

      tabs.Tab opcional