Detectores de eventos: páginas interactivas

Una página puede esperar a que una persona actúe. Un evento informa de algo que ocurrió y un detector de eventos es la función que se llama en respuesta. Registrar un detector configura esa respuesta; no realiza la acción inmediatamente.

Añade la función al elemento

Selecciona un elemento que ya exista, elige el nombre exacto del evento y pasa una función:

const button = document.querySelector("#like");
let likes = 0;
button.addEventListener("click", function () {
  likes = likes + 1;
  button.textContent = "Likes: " + likes;
});

La selección, la configuración de la variable y el registro se ejecutan cuando se ejecuta el script. Cada clic posterior ejecuta el cuerpo de la función. Después de tres clics, el botón muestra «Likes: 3». Mantener likes fuera de la función conserva el total entre clics; poner let likes = 0 dentro lo reiniciaría cada vez.

Pasa una referencia a la función, como showMenu, sin paréntesis. En button.addEventListener("click", showMenu()), JavaScript llama a showMenu inmediatamente y pasa su valor de retorno como detector. Para proporcionar un argumento más tarde, envuelve la llamada: button.addEventListener("click", () => showMenu("main"));.

Elige un evento que realmente ocurra

Los nombres son cadenas que distinguen mayúsculas de minúsculas y no llevan el prefijo «on». Usa "click", no "Click" ni "onclick". Se acepta un nombre inventado sin error, pero el navegador no lo emitirá para un clic. Entre las familias habituales están los eventos de puntero como pointerdown y pointerup, los eventos de teclado como keydown, los eventos de formulario como input y submit, y los eventos de foco como focusin. DOMContentLoaded tiene su propia combinación exacta de mayúsculas y minúsculas.

Configura el elemento adecuado en el momento adecuado

Un script en la cabecera puede ejecutarse antes de que exista un botón. La selección devuelve entonces null, y llamar a addEventListener sobre él genera un error. Carga un script externo con defer, colócalo después del marcado o registra la configuración en el evento DOMContentLoaded del documento. Un elemento creado posteriormente necesita configuración después de su creación o un detector en un nodo antecesor.

querySelectorAll devuelve una colección de nodos (NodeList), no un solo destino de evento. Registra detectores en sus elementos:

document.querySelectorAll(".tab").forEach((tab) => {
  tab.addEventListener("click", selectTab);
});

Permite que coexistan los detectores

Los detectores con la misma configuración de captura se ejecutan en orden de registro. En el destino del evento, los detectores de captura se ejecutan antes que los que no son de captura. Volver a añadir el mismo objeto de función con el mismo tipo y configuración de captura no añade una segunda copia.

El navegador pasa un objeto de evento a tu detector. Sus propiedades explican el evento que desencadenó esa llamada concreta. Llama al parámetro event o e; tú eliges el nombre.

button.addEventListener("click", (event) => {
  console.log(event.type);
  console.log(event.currentTarget);
});

Esto registra "click" y el botón durante la llamada al detector. Registrar el objeto completo puede ayudarte a descubrir sus otras propiedades.

Distingue el origen del detector

Imagina un botón que contiene una imagen:

<button id="save" data-id="7">
  <img src="disk.svg" alt=""> Save
</button>

Al hacer clic en el texto «Save», el botón también es el destino. El texto forma parte del botón; no se convierte en un elemento de destino independiente.

Esta diferencia importa al leer datos. La imagen no tiene el data-id del botón, por lo que event.target.dataset.id es undefined al hacer clic en la imagen. Un detector registrado directamente en el botón puede leer event.currentTarget.dataset.id. Un detector en un contenedor más grande puede encontrar el botón deseado con event.target.closest("button") y comprobar que existe una coincidencia.

Lee los detalles de este evento

Todo evento tiene un type, un target y un currentTarget. El booleano bubbles indica si se propaga de vuelta hacia arriba por los nodos antecesores. cancelable indica si el código puede cancelar su acción predeterminada y defaultPrevented registra si se ha producido esa cancelación. timeStamp registra el momento de creación del evento en milisegundos con respecto al origen temporal de la página.

Las distintas familias de eventos añaden detalles útiles. Un click moderno proporciona un PointerEvent, que hereda propiedades de eventos de ratón como clientX, clientY y button. Un KeyboardEvent añade key, code e indicadores de teclas modificadoras. Un detector de input puede usar event.target.value para leer el nuevo texto del campo.

Para un detector de galería, event.target.tagName podría ser "IMG" al hacer clic en una foto o "DIV" al hacer clic en el espacio entre fotos. Maneja el caso que realmente se indique. No supongas que todos los eventos dentro de un contenedor provienen del mismo tipo de hijo.

Usa el valor mientras se ejecuta el detector

En un detector con una función normal, this equivale a event.currentTarget. Una función flecha toma this del código que la rodea; no recibe el elemento como this. Usar event.currentTarget funciona con ambos estilos de función.

Después del despacho, currentTarget se restablece a null. Una consola puede mostrar ese valor posterior cuando expandes un evento registrado anteriormente. Registra event.currentTarget directamente dentro del detector para inspeccionar el elemento durante la llamada.

Un detector debe permanecer activo mientras lo necesite la función a la que sirve. Para una interacción temporal con el teclado, conserva la referencia a la función para poder eliminarla cuando se cierre la interacción.

Elimina la misma función

function onKey(event) {
  console.log(event.key);
}
document.addEventListener("keydown", onKey);
// When the feature closes:
document.removeEventListener("keydown", onKey);

La eliminación requiere que coincidan el tipo de evento, el objeto de función y la configuración de captura. Una función anónima también puede eliminarse si se guarda su referencia, como en const handler = () => save();. Escribir una nueva () => save() en la llamada de eliminación crea una función distinta, aunque el código parezca idéntico.

Elige las opciones de registro

Un aviso de bienvenida de una sola ejecución puede usar { once: true }. Una función con varios detectores puede darles una misma señal:

const controller = new AbortController();
window.addEventListener("pointermove", moveCursor, {
  signal: controller.signal
});
window.addEventListener("keydown", onKey, {
  signal: controller.signal
});
// Close the feature:
controller.abort();

La cancelación elimina ambos registros. Un controlador cancelado no se puede restablecer; crea uno nuevo para un nuevo periodo de actividad. Para eliminar con removeEventListener, repite capture: true si se usó en el registro. once, signal y passive no forman parte de los criterios de coincidencia para la eliminación.

La llamada a preventDefault() de un detector pasivo se ignora. Los navegadores suelen hacer pasivos por defecto ciertos detectores relacionados con el desplazamiento en destinos a nivel de documento, incluidos wheel, touchstart y touchmove; usa ahí { passive: false } de forma explícita cuando sea necesario cancelar la acción.

Evita la acumulación de funciones de devolución de llamada

Si cada clic en «Iniciar» añade un nuevo detector anónimo al tablero, iniciar dos veces hace que un clic en el tablero ejecute dos funciones de devolución de llamada. Registra el detector del tablero una vez, reutiliza el mismo objeto de función o cancela el grupo anterior antes de sustituirlo. Las distintas funciones de devolución de llamada con once aún pueden acumularse antes de ejecutarse.

Desconectar un elemento conserva sus detectores. Funcionan si se vuelve a insertar y dispatchEvent() puede llegar a ellos mientras está desconectado. El elemento puede ser recogido por el recolector de basura cuando ya no se puede acceder a él ni a sus detectores. Un detector de window o document permanece registrado hasta que se elimine explícitamente.

Envía un evento personalizado

const event = new CustomEvent("cart:add", {
  detail: { id: 42 },
  bubbles: true
});
item.dispatchEvent(event);

Los detectores leen event.detail.id. El despacho llama a los detectores inmediatamente, antes de terminar. bubbles: true permite que los nodos antecesores también lo reciban. Un evento enviado con dispatchEvent() tiene isTrusted igual a false; se puede confiar en los eventos despachados por el navegador incluso cuando los haya provocado una API como focus().

Un clic dentro de un botón también puede ser recibido por los nodos antecesores del botón. La propagación es el recorrido del evento por el árbol del documento. Seguir ese recorrido explica tanto los útiles detectores compartidos como las acciones adicionales inesperadas.

Sigue tres fases

1. Captura: el evento desciende desde window por los nodos antecesores hacia el destino.
2. Destino: los detectores se ejecutan en el elemento donde comenzó el evento.
3. Burbujeo: un evento que se propaga por burbujeo vuelve a subir por los nodos antecesores hasta window.

La propiedad eventPhase indica 1 para captura, 2 en el destino y 3 para burbujeo. Un detector registrado sin opciones se ejecuta en el destino o en el recorrido de burbujeo. Un detector con { capture: true } se ejecuta en el recorrido descendente, incluido el destino si se registró allí.

Sigue un clic concreto

<div id="outer">
  <div id="inner">
    <button>Go</button>
  </div>
</div>

Supón que el botón y cada div tienen detectores de clic normales que registran sus nombres. Al hacer clic en «Go» se registra «button», «inner» y después «outer». Al hacer clic en una zona vacía de inner se registra «inner» y después «outer»; el botón no está en la ruta de ese evento.

Ahora añade un detector de captura a outer. Un clic en el botón registra primero «outer (capture)» y después «button», «inner» y «outer» de los detectores normales. El detector de captura recibe el clic antes que los descendientes. Después de outer, el evento puede continuar por body, html, document y window si hay detectores registrados allí.

Es un solo evento, no un nuevo clic creado en cada nodo antecesor. target sigue siendo el botón durante todo el recorrido. currentTarget cambia a medida que se ejecuta cada detector. En el detector exterior, leer target sigue identificando el botón original.

Comprueba qué eventos se propagan por burbujeo

La propiedad bubbles del evento indica si tiene una fase de burbujeo. Los eventos sin burbujeo todavía pueden ser observados por un detector de captura de un nodo antecesor. Para manejar los cambios de foco mediante un detector normal en un contenedor, elige focusin o focusout.

Explica un error de acciones anidadas

Una tarjeta de producto abre una vista de detalles cuando se hace clic en ella. Su botón «Eliminar» elimina el producto. Al hacer clic en ese botón primero se elimina el producto, después el evento llega al detector de la tarjeta y abre la vista de detalles. La ruta del evento explica por qué se ejecutan ambas funciones de devolución de llamada.

La tarjeta puede ignorar los clics de eliminación con if (event.target.closest(".remove")) return;. Como alternativa, el botón puede detener la propagación. Filtrar en la tarjeta conserva el evento para otros nodos antecesores que puedan necesitarlo.

Un detector puede cambiar lo que ocurre después de un evento o por dónde se propaga. Son decisiones distintas. Un evento de enlace puede seguir propagándose por burbujeo incluso después de cancelar la navegación.

Sustituye una acción del navegador

Una acción predeterminada es un comportamiento que proporciona el navegador: seguir un enlace, enviar un formulario, alternar una casilla de verificación, insertar texto, desplazar la página con la barra espaciadora o mover el foco con Tab. Usa preventDefault() cuando tu código sustituya esa acción:

help.addEventListener("click", (event) => {
  event.preventDefault();
  openHelpPanel();
});

Para un enlace a /help, esto abre el panel sin navegar. El enlace sigue ofreciendo su destino cuando JavaScript no se ejecuta.

Solo se pueden cancelar los eventos cancelables. Examina event.cancelable; defaultPrevented registra si la cancelación se realizó correctamente. input ocurre después de que cambie el valor y no es cancelable. Llamar a preventDefault() ahí no elimina el texto insertado. Un evento beforeinput cancelable es el lugar adecuado para interceptar una edición; cancelar un keydown pertinente puede impedir el efecto predeterminado de esa tecla.

Controla la propagación por separado

Un enlace cuyo detector solo detiene la propagación sigue navegando a su URL. Cancelar solo la navegación sigue permitiendo que un detector de clic del documento reciba el evento. Devolver false desde una función de devolución de llamada de addEventListener no hace ninguna de las dos cosas. Una propiedad o un atributo de manejo de eventos puede cancelar su acción predeterminada devolviendo false, pero tampoco detiene la propagación.

Mantén el funcionamiento compartido

Un nodo antecesor puede cerrar un menú o contar interacciones. Detener la propagación oculta el evento a ese código. A menudo, el nodo antecesor puede examinar target o defaultPrevented.

Por ejemplo, un menú se cierra solo cuando un clic cae fuera tanto del menú como de su control de apertura:

document.addEventListener("click", (event) => {
  if (!menu.contains(event.target) &&
      !menuButton.contains(event.target)) {
    menu.hidden = true;
  }
});

contains() incluye el propio elemento y sus descendientes. Comprobar el control de apertura es importante porque el clic que abre el menú también se propaga por burbujeo hasta el documento. Sin esa segunda comprobación, el menú recién abierto se cerraría inmediatamente.

Cancela solo una acción que manejes

En un detector de teclado, comprueba la tecla antes de cancelar. Cancelar todas las teclas bloquea la escritura normal y puede impedir que Tab mueva el foco. En un detector pasivo, la cancelación se ignora por completo.

La delegación de eventos sitúa un detector en un nodo antecesor estable y usa el origen del evento para elegir una acción. Es útil cuando una lista tiene muchos elementos o cuando el código crea elementos nuevos después de la configuración.

Encuentra el control deseado

Un clic que se propaga por burbujeo llega a la lista independientemente de cuál de sus descendientes se haya pulsado. Parte de event.target, encuentra el control coincidente más cercano y descarta los clics que no correspondan:

const list = document.querySelector("#todos");
list.addEventListener("click", (event) => {
  const button = event.target.closest(".remove");
  if (!button || !list.contains(button)) return;
  const item = button.closest("li");
  console.log("Removing item " + item.dataset.id);
  item.remove();
});

La lista contiene elementos como <li data-id="7">Buy milk <button class="remove">Remove</button></li>. El detector pertenece a la lista, por lo que un elemento nuevo con el mismo marcado funciona inmediatamente después de insertarse.

Sigue en el código un clic en un icono. El destino es el icono, closest(".remove") encuentra su botón y button.closest("li") encuentra el elemento de lista. Su data-id identifica el elemento en el mensaje. Por último, remove() modifica la página.

Conserva las dos comprobaciones

Comprobar solo event.target.matches(".remove") deja fuera los clics en iconos porque el propio icono no coincide. closest() comprueba el destino y sube por sus nodos antecesores. En un detector delegado, currentTarget es la lista; no se convierte en el botón encontrado.

Dirige varias acciones

Los atributos de datos permiten que un detector de barra de herramientas elija entre acciones conocidas:

const actions = { bold: makeBold, italic: makeItalic,
  clear: clearText };
toolbar.addEventListener("click", (event) => {
  const button = event.target.closest("button[data-action]");
  if (!button || !toolbar.contains(button)) return;
  const action = actions[button.dataset.action];
  if (typeof action === "function") action();
});

Un botón con data-action="clear" selecciona clearText. La comprobación de la función maneja una acción desconocida sin intentar llamar a undefined.

Elige un evento adecuado

La delegación funciona con eventos que se propagan por burbujeo, además de los clics. Un solo detector de input en un formulario puede pasar event.target a una función que compruebe campos. Para delegar cambios de foco, usa focusin o focusout; los eventos normales focus y blur no se propagan por burbujeo. Para las transiciones al pasar el puntero, usa eventos over/out que se propaguen por burbujeo cuando necesites delegación.

Una llamada a stopPropagation() de un descendiente puede impedir que un evento llegue al contenedor. Cuando un detector delegado parezca inactivo, comprueba el tipo de evento, el destino, la coincidencia con el selector y si algo debajo del contenedor detuvo el recorrido.

La entrada del teclado va al elemento que tiene el foco, disponible como document.activeElement, y después se propaga por burbujeo. Por tanto, un detector en el documento puede recibir teclas tanto de campos como de otros controles. Ese alcance hace útiles los atajos de teclado, pero también significa que pueden interrumpir la escritura.

Elige la propiedad por su significado

En un teclado AZERTY, la posición marcada con Q en un teclado estadounidense produce key "a" y code "KeyQ". Usa key para el significado, como Escape para cerrar o una letra como atajo. Usa code para posiciones fijas, como las teclas de movimiento en un juego. El key de la barra espaciadora es un solo espacio, no "Space".

keydown se dispara en la pulsación inicial y puede repetirse mientras se mantiene pulsada la tecla. Las llamadas repetidas tienen event.repeat === true. keyup se dispara al soltarla. Usa keydown en lugar del evento obsoleto keypress.

Maneja un atajo con precisión

document.addEventListener("keydown", (event) => {
  if ((event.ctrlKey || event.metaKey) &&
      event.key.toLowerCase() === "s") {
    event.preventDefault();
    saveDraft();
  }
});

Esto maneja Ctrl+S y Comando+S. Convertir a minúsculas permite aceptar también "S". La cancelación sustituye la acción de guardar página del navegador solo para el atajo que coincide. Otros indicadores de teclas modificadoras son shiftKey y altKey.

Para un atajo de una sola letra en toda la página, omite los contextos de escritura antes de actuar:

if (event.target.matches("input, textarea, select") ||
    event.target.isContentEditable) return;
if (event.repeat) return;

La primera comprobación protege la entrada de texto. La segunda hace que una acción se ejecute una vez por cada pulsación física. No canceles Tab en toda la página; es la forma en que avanzan los usuarios de teclado.

Escucha el texto después de que cambie

Para una tecla normal que produce un carácter, la secuencia es keydown, beforeinput, input y después keyup. Leer value en keydown da el valor anterior a la inserción de ese carácter. Usa input para una vista previa del texto o un contador de caracteres. También maneja ediciones como pegar y dictar, que no necesitan una pulsación de tecla correspondiente.

Observa los cambios de foco

focus y blur indican que se recibe o se pierde el foco sin propagarse por burbujeo. focusin y focusout sí se propagan, por lo que un formulario puede observar sus campos mediante un solo detector. relatedTarget identifica el otro elemento implicado en el cambio, o null cuando no hay ninguno.

password.addEventListener("focus", () => {
  hint.hidden = false;
});
password.addEventListener("blur", () => {
  hint.hidden = true;
});

La indicación está disponible cuando el campo recibe el foco, también mediante Tab. Llamar a element.focus() mueve el foco desde el código; la siguiente entrada del teclado va entonces a ese elemento.

Una persona puede usar un ratón, un dedo, un lápiz o un teclado. Elige un evento según la interacción que necesites. click expresa activación; los eventos de puntero describen la pulsación, el movimiento y la liberación.

Mantén las acciones disponibles mediante el teclado

Un botón nativo emite click cuando se activa con Enter o la barra espaciadora. Un enlace con foco lo hace con Enter. Conectar una acción solo a pointerdown o mousedown deja fuera esas activaciones de teclado. Usa click para acciones como abrir un panel; usa pointerdown cuando el trabajo deba comenzar al pulsar, como al arrastrar.

Un clic con puntero sigue a una pulsación y una liberación. Cuando ocurren en elementos distintos, el clic puede tener como destino su nodo antecesor común más cercano. dblclick sigue a dos clics rápidos; event.detail cuenta los clics rápidos sucesivos. auxclick maneja los clics no principales. contextmenu puede proceder de un clic secundario, una pulsación táctil larga o un comando de menú del teclado.

Usa una sola familia de eventos de puntero

pointerdown, pointermove, pointerup y pointercancel cubren el ratón, la entrada táctil y el lápiz. pointerType identifica el dispositivo como "mouse", "touch" o "pen"; pointerId distingue los punteros activos, incluidos dos dedos.

Las familias más antiguas de eventos de ratón y táctiles siguen existiendo. Los navegadores pueden emitir eventos de ratón por compatibilidad después de los eventos de puntero. Por tanto, registrar tanto pointerdown como mousedown para la misma acción puede ejecutarla dos veces.

Adapta las coordenadas a la tarea

Cuando el documento se ha desplazado 300 px hacia abajo y un clic está 100 px por debajo de la parte superior del área de visualización, clientY es 100 y pageY es 400. Mantén ambas posiciones en el mismo sistema de coordenadas al calcular el movimiento. Un cambio de destino anidado también puede cambiar el origen de las coordenadas offset.

button indica qué botón cambió en un evento de pulsación o liberación: 0 principal, 1 central, 2 secundario. buttons indica la combinación que se mantiene pulsada: el principal aporta 1, el secundario 2 y el central 4. Así, buttons === 3 significa que se mantienen pulsados el principal y el secundario; no significa que haya cambiado el botón central.

Elige el comportamiento de paso del puntero para todo un control

Los eventos over/out se propagan por burbujeo y pueden dispararse cuando el puntero cruza los límites de un hijo. Los eventos enter/leave no se propagan por burbujeo y describen la entrada o salida del elemento completo, incluidos sus hijos. Una información emergente puede evitar el parpadeo al cruzar los límites de los hijos con pointerenter y pointerleave.

Los usuarios de pantallas táctiles y de teclado no pasan el puntero. Ofrece la información esencial también al hacer clic o recibir el foco. Para un efecto visual de paso del puntero sin comportamiento adicional, CSS :hover es más sencillo que un detector.

El arrastre necesita conservar información entre varios eventos. Guarda las coordenadas iniciales del puntero y la posición inicial del elemento. Cada movimiento aplica entonces la diferencia respecto a ese punto de partida, para que el elemento no salte colocando su esquina debajo del puntero.

Calcula el desplazamiento

Una caja comienza en left: 100px; top: 50px. El puntero comienza en las coordenadas del área de visualización 220, 140 y se mueve a 260, 125. El cambio horizontal es de 40 px; el cambio vertical es de −15 px. Al sumar esos cambios a la posición inicial de la caja se obtiene left: 140px; top: 35px.

Usa coordenadas de cliente coherentes para ambas lecturas del puntero. El cálculo general es la posición inicial del elemento más el desplazamiento del puntero. No sumes cada desplazamiento completo a la posición ya actualizada de la caja, pues volverías a contar el movimiento anterior.

Guarda y captura un puntero

Para una caja sin margen y con posición absoluta dentro de un contenedor con posición relativa:

let start = null;
box.addEventListener("pointerdown", (event) => {
  if (start || event.button !== 0) return;
  start = { id: event.pointerId, x: event.clientX,
    y: event.clientY, left: box.offsetLeft,
    top: box.offsetTop };
  box.setPointerCapture(event.pointerId);
});
box.addEventListener("pointermove", (event) => {
  if (!start || event.pointerId !== start.id) return;
  box.style.left = start.left +
    (event.clientX - start.x) + "px";
  box.style.top = start.top +
    (event.clientY - start.y) + "px";
});
function endDrag(event) {
  if (start && event.pointerId === start.id) start = null;
}
box.addEventListener("pointerup", endDrag);
box.addEventListener("pointercancel", endDrag);

El ID almacenado descarta los movimientos y la liberación de un segundo puntero. offsetLeft y offsetTop proporcionan las posiciones iniciales como números; los estilos necesitan el sufijo "px".

La captura del puntero mantiene los eventos posteriores de ese puntero dirigidos a la caja incluso cuando este sale de ella. El navegador libera la captura después de soltar o cancelar el puntero. releasePointerCapture(id) puede liberarla antes.

Maneja la intervención del navegador

Un gesto táctil puede convertirse en desplazamiento o zoom de la página y provocar pointercancel. Termina el arrastre tanto ahí como en pointerup; de lo contrario, un estado anterior puede seguir moviendo la caja más tarde. Aplica touch-action: none a la superficie de arrastre antes de la interacción para reservar ese gesto. Limita la regla a esa superficie para que el resto de la página pueda desplazarse.

Usa user-select: none en la superficie arrastrable para evitar seleccionar texto. Establece draggable="false" en sus imágenes para impedir el comportamiento nativo de arrastre de imágenes.

Ofrece otra forma de mover

Proporciona movimiento mediante teclado para un control con foco y botones de movimiento en los que se pueda hacer clic o tocar. Las teclas de dirección por sí solas no proporcionan una alternativa al arrastre con un solo puntero. El criterio de éxito 2.5.7 de WCAG 2.2 exige esa alternativa salvo que el arrastre sea esencial o sea un comportamiento del navegador sin modificar. Los botones nativos de movimiento pueden servir tanto a usuarios de teclado como de puntero.

La API HTML independiente de arrastrar y soltar usa dragstart, dragover y drop para transferir datos, como archivos. Su secuencia de eventos es distinta de este cambio de posición basado en el puntero.

Los controles de formulario exponen distintos tipos de estado. El value de un campo de texto es una cadena de caracteres; el checked de una casilla de verificación es un booleano. Leer la propiedad adecuada es el primer paso para obtener cálculos y vistas previas fiables.

Convierte los números de forma deliberada

Incluso <input type="number"> tiene un value de tipo cadena. Con el texto "3", sumar 1 da "31". Number(input.value) + 1 da 4. Un campo numérico también ofrece valueAsNumber.

Una entrada vacía necesita una decisión propia. Number("") da 0, lo que puede hacer que una cantidad ausente parezca un cero real. Comprueba primero input.value === "" o usa valueAsNumber, que da NaN para un campo numérico vacío. Comprueba ese resultado con Number.isNaN().

Lee el estado seleccionado

El value de una casilla de verificación es su texto configurado para el envío, o "on" si no se proporciona ninguno. No indica si está marcada. Una lista desplegable indica el valor de la opción elegida. Para encontrar el propio elemento de opción seleccionado, consulta input[name="size"]:checked.

Relaciona el evento con la actualización

input informa de las ediciones del usuario mientras ocurren, incluidas la escritura y el pegado. change informa de una elección confirmada: después de que un campo de texto modificado pierda el foco, o inmediatamente cuando cambia una casilla de verificación, un botón de opción o una lista desplegable.

message.addEventListener("input", () => {
  counter.textContent = 280 - message.value.length +
    " characters left";
});

Después de «Hello», se han usado cinco caracteres y el contador muestra «275 characters left». Un detector de keydown se ejecutaría antes de que el nuevo carácter entrara en el valor y no detectaría el pegado mediante un menú. Asignar message.value desde el código no dispara ni input ni change; llama también directamente a la función de actualización.

Recopila los campos con nombre de un formulario

form.elements.email.value accede a un control por su nombre o ID. Usa form.elements["first-name"] para un nombre con guion. El envío usa nombres: un ID por sí solo no incluye un campo en los datos.

const data = new FormData(form);
const email = data.get("email");
const topics = data.getAll("topics");

FormData recopila los pares de nombre y valor actuales que cumplen los requisitos. Se omiten las casillas sin marcar, los controles deshabilitados y los campos sin nombre. get() devuelve el primer valor de un nombre; getAll() conserva los valores repetidos, como varios temas marcados. Los controles de archivo pueden proporcionar objetos de archivo; los controles de texto normales proporcionan cadenas de caracteres.

Object.fromEntries(data) resulta cómodo para nombres distintos, pero solo conserva el último par de los nombres repetidos. Elige getAll() cuando importe cada selección. Como input se propaga por burbujeo, un detector del formulario puede leer event.target para actualizar el campo que haya cambiado.

El envío pertenece al formulario. Escucha su evento submit para manejar por una sola vía un clic en el botón de envío, Enter en un campo de una sola línea y una llamada a requestSubmit() desde un script.

Sustituye la navegación por una actualización de la página

Normalmente, un formulario envía datos a la URL de su action y carga la respuesta. Sin una acción, el destino es la página actual. El método GET predeterminado coloca los datos en la URL. Para actualizar la página actual con JavaScript, cancela esa acción predeterminada:

const form = document.querySelector("#new-todo");
form.addEventListener("submit", (event) => {
  event.preventDefault();
  const data = new FormData(form);
  const title = data.get("title").trim();
  if (title === "") return;
  addTodo(title);
  form.reset();
});

Este formulario tiene un campo de texto habilitado llamado title. El detector elimina los espacios de los extremos, ignora un resultado vacío, añade un elemento y restablece los campos a sus valores iniciales. reset() no siempre significa dejar vacío; un control con un valor inicial vuelve a ese valor.

Si el elemento aparece brevemente y desaparece al volver a cargar la página, comprueba si falta preventDefault(). Un detector de clic solo en el botón no es el punto adecuado para manejar el formulario, especialmente cuando otra vía lo envía.

Conoce qué desencadena el envío

El envío implícito con Enter puede hacer clic en el botón de envío predeterminado habilitado. Enter en un área de texto inserta un salto de línea. Un botón dentro de un formulario es un botón de envío por defecto cuando se omite su tipo, así que un botón «Mostrar contraseña» debe usar explícitamente type="button".

Cuando hay varios botones de envío, event.submitter identifica el que se usó. Puede ser null en vías sin un botón específico, por lo que el código debe comprobarlo antes de leerlo:

const button = event.submitter;
const intent = button ? button.value : "save";
const data = button ? new FormData(form, button) :
  new FormData(form);

Un botón de envío con nombre como name="intent" value="publish" aporta ese par cuando se pasa a FormData. Una llamada a FormData(form) por sí sola no incluye el par de nombre y valor de un botón de envío.

Conserva la vía de validación

La validación integrada se ejecuta antes del evento submit. Si un campo obligatorio vacío no supera la comprobación, el navegador informa del problema y no despacha submit. Una comprobación personalizada situada solo dentro de ese detector no se ejecutará en ese intento fallido. novalidate en el formulario desactiva el paso de validación automática.

Usa requestSubmit() cuando el código necesite la vía normal de validación y del evento submit. Solicita el envío sin despachar un clic en el botón. Pasa un botón de envío concreto a requestSubmit(button) cuando deban aplicarse las opciones de envío de ese botón.

HTML puede describir muchas reglas de entrada sin una comprobación personalizada de JavaScript. El navegador comprueba esas reglas durante el envío y expone los resultados para tu código. Empieza con las restricciones que correspondan a los datos que necesitas.

Elige una restricción

Para pattern="[0-9]{5}", «12345» pasa la comprobación; «1234», «123456» y «12345a» no la pasan. El patrón abarca todo el valor, no cualquier subcadena coincidente. Una entrada vacía omite la comprobación del patrón, así que añade required cuando no se permita dejarla vacía.

La validación de correo electrónico comprueba la sintaxis, no si existe un buzón. Tanto «ann@example.com» como «ann@example» cumplen la regla de correo electrónico del navegador, mientras que «ann.example.com» no la cumple. Un patrón adicional puede imponer un formato más específico cuando la aplicación lo requiera.

Lee el motivo del fallo

El objeto validity de un campo contiene indicadores booleanos. valueMissing, typeMismatch, patternMismatch, tooShort y tooLong describen texto ausente o con formato incorrecto. rangeUnderflow, rangeOverflow y stepMismatch describen restricciones numéricas. badInput cubre una entrada que el navegador no puede convertir en un valor utilizable, y customError registra un mensaje de validez personalizada. valid es verdadero cuando ninguna restricción falla.

Para un campo numérico con min="0" max="10" step="2", 12 supera el máximo, 7 no coincide con el incremento permitido y 6 pasa la comprobación. Más de un indicador puede ser verdadero; no supongas que cada campo no válido tiene exactamente un problema.

Comprueba sin mostrar o informa de forma visible

checkValidity() devuelve un booleano y dispara invalid en los controles que no pasan la comprobación sin mostrar el mensaje del navegador. reportValidity() comprueba y también informa del problema al usuario. Llama a cualquiera de los dos en un campo o un formulario. validationMessage proporciona el mensaje en el idioma del navegador. El evento invalid no se propaga por burbujeo.

Las restricciones de longitud del texto se aplican al texto introducido por el usuario. Asignar input.value = "ab" en el código no hace que tooShort sea verdadero solo porque minlength sea 3. maxlength normalmente también impide que el usuario siga escribiendo más allá del límite.

Muestra los errores en un momento útil

:invalid se aplica inmediatamente, por lo que un campo obligatorio sin tocar ya coincide. :user-invalid espera a una interacción del usuario o a un intento de envío y puede evitar que el campo aparezca en rojo demasiado pronto. Usa también texto para explicar el error, además de un estilo visual.

novalidate omite la validación automática del envío para el formulario; formnovalidate la omite para un botón de envío. No eliminan las restricciones ni desactivan checkValidity(). Las comprobaciones del navegador ayudan a los usuarios a corregir errores; el servidor debe volver a validar los datos recibidos porque una solicitud puede evitar la página.

Una regla que implica dos campos necesita código. Por ejemplo, una confirmación debe coincidir con una contraseña, o una fecha final debe ser posterior a una fecha inicial. Mantén la regla separada de cómo y cuándo se muestra su error.

Establece y borra un error personalizado

Una cadena no vacía pasada a setCustomValidity() marca el campo como no válido y establece customError. Pasar "" borra ese error personalizado; las restricciones de obligatoriedad, patrón u otras pueden seguir sin cumplirse.

function checkMatch() {
  const matches = confirm.value === password.value;
  confirm.setCustomValidity(matches ? "" :
    "The passwords do not match.");
}
password.addEventListener("input", checkMatch);
confirm.addEventListener("input", checkMatch);

Vuelve a comprobar ambas dependencias. Cambiar la primera contraseña puede hacer que una confirmación antes correcta deje de coincidir. Un mensaje que nunca se borra mantiene el campo como no válido después de que la persona corrija la diferencia. Ejecuta también la comprobación inicial cuando los campos puedan comenzar con valores.

Los campos de fecha proporcionan cadenas ISO como "2026-03-10", independientemente del formato de fecha local que se muestre. Los valores no vacíos de estos controles se pueden comparar como texto. Si la regla indica que el final debe ser posterior al inicio, rechaza end.value <= start.value, incluida la igualdad. Trata las fechas ausentes mediante required o una comprobación independiente de valor vacío.

Explica la siguiente acción útil

Un mensaje debe identificar el problema y su corrección. Para un correo electrónico ausente, di «Introduce tu dirección de correo electrónico». Para un texto de correo con formato incorrecto, di «Introduce una dirección de correo electrónico con el formato nombre@example.com». Conserva el valor introducido para que la persona pueda editarlo.

Un campo de nombre obligatorio acepta espacios porque forman una cadena no vacía. Comprueba name.value.trim() === "" cuando los espacios en blanco de los extremos no deban contar. Borra este error personalizado cuando aparezca texto significativo.

Conecta los mensajes con los controles

<label for="email">Email</label>
<input id="email" name="email" type="email"
  required aria-describedby="email-error">
<p id="email-error"></p>

Coloca el error en ese párrafo y establece aria-invalid="true" mientras el campo tenga un error. Borra el texto y elimina aria-invalid o establécelo en "false" después de la corrección. aria-describedby conecta la explicación con el campo para la tecnología de asistencia. Usa texto; un borde rojo por sí solo no puede indicar a todo el mundo qué ha fallado.

Elige el flujo de validación

Para mensajes completamente personalizados, añade novalidate y usa un detector de submit en el formulario. Actualiza las reglas personalizadas, examina la validez de los campos, escribe sus mensajes e impide el envío cuando alguno no sea válido. Mueve el foco al primer campo no válido o a un resumen de errores con enlaces. Si JavaScript también maneja localmente el envío correcto, cancela asimismo ese envío predeterminado.

Evita informar de un texto de correo electrónico incompleto en cada pulsación inicial. Una secuencia útil consiste en mostrar los errores después de perder el foco o de enviar el formulario y, después, volver a comprobar un error ya mostrado en input.

Un control necesita algo más que una respuesta al clic. Las personas deben poder encontrarlo, llegar a él, comprender su propósito, accionarlo y ver dónde está el foco. HTML nativo ya proporciona gran parte de este comportamiento.

Elige el elemento adecuado para la tarea

Usa un <button> para una acción, un <a href> para la navegación y un control de formulario con etiqueta para la entrada de datos. <details> con <summary> proporciona un control de despliegue de contenido. Aplica estilos CSS a estos elementos para que encajen en la página. Un botón con foco se activa mediante Enter o la barra espaciadora sin un detector de teclado adicional.

Un div con un detector de clic no tiene ninguna de las características semánticas ni del comportamiento de teclado integrados del botón. Asignarle role="button" cambia lo que anuncia la tecnología de asistencia, pero no permite que reciba el foco ni convierte las pulsaciones de teclas en clics.

Mantén un orden de foco predecible

tabindex="0" añade un elemento a la secuencia normal de tabulación en el orden del documento. tabindex="-1" permite dar el foco mediante código sin añadir una parada de tabulación. Los valores positivos mueven elementos por delante de la secuencia habitual y son difíciles de mantener; evítalos.

Ninguna de las dos configuraciones añade comportamiento de activación. Un botón personalizado que puede recibir el foco sigue necesitando un detector para manejarlo con el teclado. Un rol, una parada de tabulación y una función de devolución de llamada resuelven partes distintas de la interacción.

Da un nombre a cada control

Un lector de pantalla usa un nombre accesible para distinguir los controles. Un botón de texto puede usar su texto visible. Un campo de texto o una lista desplegable necesita una etiqueta asociada, como <label for="email">Email</label> junto con id="email". aria-labelledby puede hacer referencia a texto visible en otro lugar; aria-label puede proporcionar un nombre cuando no hay texto visible adecuado.

Un botón de cierre que solo contiene un icono puede ser <button type="button" aria-label="Close">×</button>. El nombre describe la acción en lugar de hacer que el usuario deduzca qué significa el símbolo.

Muestra y aplica el estado

Mantén un indicador de foco visible. Si sustituyes el contorno predeterminado, proporciona una alternativa clara con :focus-visible, por ejemplo outline: 3px solid #1a73e8. Eliminarlo sin sustituirlo oculta la posición del usuario de teclado.

Un botón nativo deshabilitado sale de la secuencia de tabulación y no puede activarse normalmente. aria-disabled="true" solo comunica que no está disponible. La acción de clic y teclado de un control personalizado debe comprobar ese estado y terminar sin actuar. Centralizar esa comprobación en la función de activación mantiene la coherencia entre ambas vías de entrada.

Un control personalizado debe dar el mismo resultado independientemente de cómo se active. Mantén la acción en una sola función, dirige a ella el uso del teclado y del puntero, y actualiza el estado que leen tanto los estilos como la tecnología de asistencia.

Da activación mediante teclado a un botón personalizado

fakeButton.addEventListener("click", activate);
fakeButton.addEventListener("keydown", (event) => {
  if (event.key === "Enter" || event.key === " ") {
    event.preventDefault();
    activate();
  }
});

Esto es para un botón personalizado que puede recibir el foco. Cancelar la barra espaciadora impide que la página se desplace durante la acción. Un botón nativo ya produce clics al activarse con el teclado, por lo que añadirle una segunda vía de teclado puede ejecutar la acción dos veces.

Elige el estado que corresponda al control

Un botón de alternancia «Silenciar» conserva esa etiqueta y cambia aria-pressed. Si el diseño cambia la etiqueta de la acción a «Activar sonido», omite aria-pressed. Una casilla de verificación usa role="checkbox" y la barra espaciadora para alternar su estado; un interruptor usa role="switch" para el estado de activado o desactivado.

Los atributos contienen cadenas de caracteres. Compara getAttribute("aria-expanded") con "true", no con el booleano true:

detailsButton.addEventListener("click", () => {
  const open = detailsButton.getAttribute(
    "aria-expanded") === "true";
  detailsButton.setAttribute("aria-expanded", String(!open));
  panel.hidden = open;
});

Cuando open era verdadero, el nuevo estado es falso y el panel queda oculto. aria-controls puede identificar el panel por su ID. Los elementos nativos <details> y <summary> proporcionan el comportamiento de despliegue sin este script.

Usa el atributo de estado como fuente para los estilos, por ejemplo [aria-pressed="true"], para que los estados visible y anunciado cambien juntos. Cierra los elementos emergentes con Escape y devuelve el foco a su control de apertura.

Da al grupo una sola parada de tabulación

Las pestañas, las barras de herramientas y los grupos de botones de opción usan Tab para entrar o salir del grupo y las teclas de dirección para moverse dentro de él. El índice de tabulación móvil mantiene el elemento actual en 0 y los demás en -1. Al moverse, establece el elemento anterior en -1, el nuevo en 0 y da el foco al nuevo elemento.

Para tres elementos, moverse a la derecha desde el índice 2 vuelve al 0 con (2 + 1) % 3. Moverse a la izquierda desde 0 usa (0 - 1 + 3) % 3 para llegar a 2. Añade la longitud antes de la operación de resto porque en JavaScript -1 % 3 es −1.

Comprueba con el teclado: entra en el control, ve el foco, actívalo con las teclas adecuadas, muévete dentro de un grupo y cierra un elemento emergente con Escape. Comprueba el estado visible y el estado ARIA en cada cambio.

El foco determina adónde va la siguiente acción del teclado. Si el control que tiene el foco desaparece, el usuario puede perder su posición. Trata el foco como parte de la actualización de la página, especialmente al abrir un cuadro de diálogo, eliminar un elemento o informar de un error.

Abre un cuadro de diálogo y vuelve a su control de apertura

Recuerda el elemento que tiene el foco antes de abrir. Mueve el foco a la nueva interacción y después restablécelo al cerrar:

let opener;
openButton.addEventListener("click", () => {
  opener = document.activeElement;
  dialog.showModal();
});
dialog.addEventListener("close", () => {
  if (opener && opener.isConnected) opener.focus();
});

showModal() en un cuadro de diálogo nativo mueve el foco a su interior y hace que el resto de la página sea inerte, por lo que no se puede hacer clic en ella ni darle el foco mientras el cuadro modal está abierto. Escape normalmente provoca un evento cancel seguido del cierre y un evento close. Un detector de cancel puede impedir el cierre si la aplicación necesita ese comportamiento.

Elige una ubicación inicial útil para el foco en el cuadro de diálogo, como su primer control pertinente. Para un elemento emergente personalizado, el código debe mover el foco de forma deliberada. Cuando el control de apertura original ya no exista, elige un control útil cercano en lugar de intentar dar el foco a un elemento desconectado.

Permite que un destino útil reciba el foco

Un encabezado o un resumen de errores normalmente no puede recibir el foco. Asígnale tabindex="-1" antes de llamar a .focus(). Podrá recibir el foco de forma deliberada sin convertirse en una parada adicional durante la navegación normal con Tab. Usa 0 solo cuando pertenezca a esa secuencia normal.

Conserva la posición después de eliminar

Antes de eliminar un elemento de lista cuyo botón de eliminación tiene el foco, encuentra el siguiente destino útil. Da el foco al botón del siguiente elemento; si no hay un siguiente elemento, usa el botón del anterior. Si la lista queda vacía, da el foco a su encabezado con tabindex="-1".

Encontrar el destino antes de eliminar evita perder la relación con los elementos vecinos. No envíes el foco a la parte superior del documento después de cada eliminación; la persona debe poder seguir trabajando cerca del cambio.

Mantén el foco en una interacción que continúa

Un elemento emergente puede cerrarse cuando el foco sale de toda su área. El evento focusout, que se propaga por burbujeo, proporciona el destino:

menu.addEventListener("focusout", (event) => {
  if (!menu.contains(event.relatedTarget)) {
    menu.hidden = true;
  }
});

Moverse entre dos controles del menú no lo cierra porque el destino permanece dentro. Un destino null también está fuera; contains(null) es falso. No devuelvas automáticamente el foco al control de apertura cuando el usuario se haya movido de forma intencionada a otro control de la página.

Haz que los cambios sean predecibles

Después de una validación personalizada fallida de un formulario, da el foco al primer campo no válido o a un resumen de errores que enlace a ellos. La validación integrada ya da el foco a un campo que no supera la comprobación. Mantén disponible el texto del error para que la persona sepa qué corregir.

No saltes a un campo nuevo mientras el usuario escribe ni navegues en cuanto cambie una lista desplegable. Deja que una acción clara confirme el cambio. El movimiento del foco debe ayudar a realizar una acción deliberada o a recuperarse de un error, sin interrumpir la entrada normal.