⌨️ KeyboardShortcutsService – Guía de uso

KeyboardShortcutsService es un servicio inyectable que proporciona una manera centralizada y eficiente de gestionar atajos de teclado globales en toda la aplicación. Permite registrar y desregistrar combinaciones de teclas para ejecutar acciones específicas, optimizando el rendimiento al operar fuera de la zona de Angular.

---

📁 Inyección del Servicio

El servicio está provisto en root (providedIn: 'root'), por lo que no necesitas añadirlo a ningún providers de módulo o componente. Simplemente inyéctalo en el constructor de tu componente o servicio.

// En tu componente.ts (o servicio)
import { Component, OnDestroy, OnInit, inject } from '@angular/core';
import { KeyboardShortcutsService } from '@alpura/commons';

@Component({
  selector: 'app-mi-componente',
  template: `...`,
})
export class MiComponente implements OnInit, OnDestroy { 
  private shortcutsService = inject(KeyboardShortcutsService);

  constructor() {}

  ngOnInit(): void {
    // Lógica para registrar atajos
  }

  ngOnDestroy(): void {
    // Lógica para limpiar atajos
  }
}

---

🚀 Uso Principal: Atajos Fijos

El servicio expone una lista de atajos predefinidos y estandarizados para acciones comunes en la aplicación.

Atajos Disponibles (KeyboardShortcutsService.SHORTCUTS)

Clave	Atajo	Acción Común
NEW	alt+n	Crear un nuevo elemento
ACCEPT	alt+a	Aceptar o guardar
CANCEL	alt+q	Cancelar o limpiar
SEARCH	alt+b	Realizar una búsqueda
HELP	alt+h	Mostrar ayuda
EXPORT_WORD	alt+w	Exportar a Word
EXPORT_EXCEL	alt+e	Exportar a Excel
EXPORT_PDF	alt+p	Exportar a PDF
DOWNLOAD	alt+d	Descargar un archivo
TOGGLE_OPTION	alt+t	Alternar una opción
SEND	alt+s	Enviar datos

registerFixedShortcuts(callbacks)

Este es el método principal para usar los atajos predefinidos. Recibe un objeto donde cada clave es el nombre de un atajo fijo y su valor es la función (callback) a ejecutar.

Ejemplo:

// Dentro de tu componente
ngOnInit(): void {
  this.shortcutsService.registerFixedShortcuts({
    NEW: (combo) => this.crearNuevoItem(combo),
    SEARCH: (combo) => this.buscarItems(combo),
    EXPORT_EXCEL: () => this.exportarDatos(),
  });
}

crearNuevoItem(combo: string) {
  console.log(`Atajo '${combo}' presionado. Iniciando creación...`);
  // Lógica para crear un nuevo item
}

buscarItems(combo: string) {
  console.log(`Atajo '${combo}' presionado. Buscando...`);
  // Lógica para buscar
}

exportarDatos() {
  console.log('Exportando a Excel...');
  // Lógica de exportación
}

---

🛠️ Atajos Personalizados

registerCustomShortcut(options)

Si necesitas un atajo que no está en la lista de fijos, puedes registrarlo con este método.

Importante: El servicio lanzará un error si intentas registrar una combinación de teclas que ya está definida como un atajo fijo.

Ejemplo:

// Registrando el atajo 'ctrl+i' para imprimir
this.shortcutsService.registerCustomShortcut({
  modifier: 'ctrl',
  key: 'i',
  callback: (combo) => {
    console.log(`Atajo personalizado '${combo}' activado.`);
    window.print();
  },
});

---

🧹 Gestión del Ciclo de Vida (¡Muy Importante!)

Para evitar fugas de memoria y comportamientos inesperados (como que un atajo siga funcionando después de que el componente se haya destruido), siempre debes limpiar los atajos que registraste.

unregisterShortcut(shortcutKey)

Elimina un atajo fijo específico.

unregisterAllFixedShortcuts()

Elimina todos los atajos registrados. Este es el método más común y seguro para usar en ngOnDestroy.

Ejemplo de limpieza:

// En tu componente
ngOnDestroy(): void {
  // Esto desregistra todos los atajos que este componente pudo haber registrado.
  this.shortcutsService.unregisterAllFixedShortcuts();
  console.log('Atajos de teclado limpiados.');
}

---

📬 Soporte

Para dudas o mantenimiento del servicio KeyboardShortcutsService, contactar al equipo de arquitectura.