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.

Manifiesto

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

"commands"

Conceptos y uso

La API de Commands permite que los desarrolladores de extensiones definan comandos específicos y los vinculen a un combinación de teclas. Cada comando que acepte una extensión debe declararse como propiedad del El 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 y plataformas de Google Cloud.

• 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 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 extensiones. Se requieren descripciones para los estándares 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 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. Intentando cargar una extensión con una clave mal escrita en mayúsculas y minúsculas provocará un error de análisis de manifiesto en durante el tiempo de 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)

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

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 "mac". atajo.

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

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

Nota: No se permiten combinaciones de teclas que involucren Ctrl+Alt para evitar conflictos con el Tecla AltGr.

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 usando onCommand.addListener. Por ejemplo:

service-worker.js:

chrome.commands.onCommand.addListener((command) => {
  console.log(`Command: ${command}`);
});

Comandos de acción

Se incluyen _execute_action (Manifest V3), _execute_browser_action (Manifest V2) y Los comandos _execute_page_action (Manifest V2) están reservados para la acción de activar tu acción. acción del navegador o de página, respectivamente. Estos comandos no envían command.onCommand como comandos estándar.

Si necesitas realizar alguna acción en función de la apertura de la ventana emergente, considera escuchar un 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án enfocados, las combinaciones de teclas de comandos están inactivas. A partir de Chrome 35, los desarrolladores de extensiones pueden de manera opcional, marca un comando como “global”. Los comandos globales también funcionan cuando Chrome no está enfocado.

Nota: ChromeOS no admite comandos globales.

Las sugerencias de combinaciones de teclas para comandos globales se limitan a Ctrl+Shift+[0..9]. Este es un medidas de protección para minimizar el riesgo de anular los accesos directos en otras aplicaciones, ya que si, por Por ejemplo, Alt+P se permitía como global, la combinación de teclas para abrir un diálogo de impresión. podrían no funcionar en otras aplicaciones.

Los usuarios finales tienen la libertad de reasignar comandos globales a su combinación de teclas preferida usando la IU expuesta. a las 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 su (más básico, un comando solo requiere una declaración de comando en el manifiesto de la extensión y un 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 al directorio acción. En el siguiente ejemplo, se inserta una secuencia de comandos de contenido que muestra un alerta en la página actual cuando el usuario hace clic en la acción de la extensión o activa 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 acceso directo que ya usa otra extensión, el de la segunda extensión no se registrará como se espera. Puedes proporcionar un perfil de usuario final al anticipar esta posibilidad y comprobar que no haya 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.
    }
  });
}

Tipos

Command

Propiedades

• descripción

  string opcional

  La descripción del comando de extensión

• nombre

  string opcional

  El nombre del comando Extension

• atajo

  string opcional

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

Métodos

getAll()

Promesa

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

Muestra todos los comandos de extensión registrados para esta extensión y su combinación de teclas (si está activa). En versiones anteriores a 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

  • comandos

    Comando

Muestra

• Promesa<Command[]>

  Chrome 96 y versiones posteriores

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

  función

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

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

  • comando

    string

  • tab

    tabs.Tab opcional