Eventos de teclado y atajos propios: implementarlos sin romper nada

En la primera lección vimos qué exige 2.1.4 Atajos de teclado y en la anterior escribimos manejadores para las flechas. En cuanto una aplicación crece (un gestor de expedientes, un editor, un panel de administración), aparecen atajos propios: Ctrl+K para buscar, / para ir al buscador, ? para la ayuda. Implementarlos bien exige conocer la API de eventos de teclado, las particularidades del teclado español y las combinaciones que ya están ocupadas por el navegador, el sistema y los lectores de pantalla. Un atajo mal elegido no solo no ayuda: impide escribir una arroba o deja sin funciones a quien usa NVDA.

keydown, key y code

El evento para reaccionar a una pulsación es keydown. Se dispara al pulsar y se repite mientras se mantiene la tecla (la propiedad e.repeat indica las repeticiones). keyup tiene usos puntuales; keypress y las propiedades keyCode y which están obsoletas y no deberías usarlas en código nuevo.

Cada evento trae dos propiedades que conviene no confundir:

• e.key: el valor lógico de la tecla, es decir, el carácter que produce ("a", "A", "/") o su nombre ("Enter", "Escape", "ArrowDown"). Depende de la distribución del teclado.
• e.code: la posición física de la tecla ("KeyA", "Digit7"), con nombres tomados del teclado estadounidense e independiente de la distribución.

Regla práctica: para atajos de letra o símbolo, usa key, que coincide con lo que la persona ve impreso en su tecla. Reserva code para cuando importe la posición, como en un juego que usa las teclas de dirección de la mano izquierda.

if (e.code === 'Slash') buscador.focus(); // incorrecto

Modificadores y teclado español

Las propiedades ctrlKey, altKey, shiftKey y metaKey indican qué modificadores estaban pulsados. metaKey corresponde a la tecla Cmd en macOS, donde las convenciones usan Cmd allí donde Windows usa Ctrl; lo más sencillo es aceptar ambas: (e.ctrlKey || e.metaKey) && e.key === 'k'.

Dos trampas propias de nuestro teclado:

• AltGr equivale a Ctrl+Alt en Windows. En un teclado español, la arroba, la almohadilla, el euro, los corchetes, las llaves y la barra invertida se escriben con AltGr, y Windows notifica esa tecla como Ctrl+Alt. Si defines Ctrl+Alt+E para exportar, cada vez que alguien escriba «€» exportará el documento; con Ctrl+Alt+2, no podrá escribir una dirección de correo. Evita las combinaciones Ctrl+Alt con letras, números y signos.
• Teclas muertas y métodos de entrada. Para escribir «á» se pulsa primero la tecla de la tilde, que llega como e.key === "Dead", y luego la «a». En idiomas como el chino o el japonés, la composición de caracteres marca los eventos con e.isComposing. Si un campo de texto procesa keydown para construir o filtrar lo que se escribe, romperá estas entradas. Para reaccionar a lo escrito, escucha el evento input.

Combinaciones ocupadas

No existe un espacio de atajos libre en todos los entornos. Antes de elegir, revisa con quién puedes chocar:

• El navegador. Algunas combinaciones no se pueden capturar desde una página (en Chrome, por ejemplo, Ctrl+T, Ctrl+W o Ctrl+N). Otras sí se pueden capturar, como Ctrl+F o Ctrl+P, pero la persona espera su comportamiento habitual: sustitúyelas solo si ofreces algo equivalente, como una búsqueda dentro de un documento largo que el navegador no puede hacer.
• El sistema operativo. Alt+Tab, las combinaciones con la tecla Windows o Ctrl+Alt+Supr nunca llegan a la página. En Windows, Alt+Mayús puede cambiar la distribución del teclado si hay varias instaladas.
• Los lectores de pantalla. NVDA usa Insert (y opcionalmente Bloq Mayús) como tecla propia; NVDA y JAWS usan Ctrl+Alt+flechas para recorrer tablas; VoiceOver en macOS usa Ctrl+Opción como prefijo. Además, en modo exploración los lectores interceptan las letras sueltas, como verás en la lección sobre tecnologías de apoyo.

Elige pocos atajos, compruébalos contra las listas de combinaciones de los navegadores y lectores más usados, muéstralos en la interfaz y permite reasignarlos. Así cumples 2.1.4 si son de una sola tecla y evitas conflictos en todos los casos.

Un atajo de una sola tecla bien implementado

Recordemos las condiciones de 2.1.4: un atajo de una sola tecla debe poder desactivarse, reasignarse o estar limitado al componente con foco. Además, por pura usabilidad, nunca debe dispararse mientras la persona escribe. Este manejador reúne las comprobaciones necesarias:

const ajustes = cargarPreferencias(); // { atajosDeUnaTecla: true }, guardado en el perfil

document.addEventListener('keydown', (e) => {
  if (!ajustes.atajosDeUnaTecla) return;            // 2.1.4: se pueden desactivar
  if (e.defaultPrevented || e.isComposing) return;   // otro componente ya lo gestionó
  if (e.ctrlKey || e.metaKey || e.altKey) return;    // no es un atajo de una tecla
  const t = e.target;
  if (t.isContentEditable || t.closest('input, textarea, select')) return; // está escribiendo

  if (e.key === '/') {
    e.preventDefault();
    document.getElementById('buscar').focus();
  } else if (e.key === '?') {
    e.preventDefault();
    abrirAyudaDeAtajos();
  }
});

Observa que no se descarta shiftKey: en el teclado español tanto / como ? requieren Mayús. Y que preventDefault() solo se llama para las teclas que el atajo usa; cualquier otra pulsación sigue su curso.

Para dar a conocer los atajos, combina tres cosas: una ayuda accesible desde la interfaz (un botón «Atajos de teclado» que abre un diálogo con la lista, y la opción de desactivarlos), la combinación visible junto a la acción (en el menú, «Exportar Ctrl+Mayús+E») y el atributo aria-keyshortcuts, que expone el atajo a las tecnologías de apoyo:

<button type="button" aria-keyshortcuts="Control+Shift+E">Exportar</button>

aria-keyshortcuts solo informa: no implementa el atajo, y no todos los lectores lo anuncian. No sustituye a mostrarlo en pantalla.

document.addEventListener('keydown', (e) => {
  e.preventDefault(); // para que el navegador no interfiera
  gestionarAtajo(e);
});

Detalles que marcan la diferencia

• Intro y Espacio en botones propios. En un botón nativo, Intro dispara el clic al pulsar y Espacio al soltar. Si reconstruyes un botón, imitar ese detalle es un refinamiento; lo imprescindible es que ambas teclas funcionen.
• Escape con jerarquía. Escape debe cerrar lo último que se abrió (el desplegable dentro del diálogo antes que el diálogo), no todo a la vez. Detén la propagación en el componente que lo gestiona.
• Teclas mantenidas. Si una acción no debe repetirse (enviar, borrar), ignora los eventos con e.repeat.
• No dupliques lo nativo. Si un button real ya ejecuta su acción en el evento click, no añadas un manejador de Intro que la llame también: el navegador ya genera el clic con esa tecla y la acción se ejecutará dos veces.

addEventListener('keydown', (e) => console.log(e.key, e.code, e.ctrlKey, e.altKey, e.shiftKey));

Resumen

• keydown es el evento correcto; keypress, keyCode y which están obsoletos.
• e.key es lo que produce la tecla y e.code su posición física; para atajos de letras y símbolos, usa key.
• En Windows, AltGr llega como Ctrl+Alt: esas combinaciones chocan con la escritura en español.
• Revisa los conflictos con navegador, sistema y lectores de pantalla; muestra los atajos y permite desactivarlos o reasignarlos.
• Nunca dispares un atajo dentro de un campo de texto ni llames a preventDefault() de forma general.