El evento popstate

El evento popstate se dispara en window cuando el usuario navega por el historial (hacia atrás, hacia delante o mediante una llamada de JavaScript a history.back). Permite que la SPA vuelva a renderizar la vista correcta en respuesta a una navegación iniciada por el navegador.

popstate se dispara al hacer clic en los botones de atrás o adelante, y al llamar a history.back(), history.forward() o history.go(n). NO se dispara cuando se llama manualmente a pushState/replaceState: son actualizaciones programáticas y la página ya tiene conocimiento de ellas.

La propiedad state del evento contiene el objeto de estado que pasó a pushState/replaceState para la entrada a la que se está navegando. Úselo para restaurar el estado de la interfaz (pestaña abierta, posición de desplazamiento) que no se encuentra en la URL.

La barra de direcciones ya se ha actualizado cuando se dispara popstate. Lea location.pathname, location.search y location.hash para encontrar la nueva URL. Combinada con el estado, esta es toda la información necesaria para renderizar la vista de destino.

popstate NO se dispara durante la carga inicial de la página, sino únicamente durante la navegación. Renderice la vista inicial a partir de location al iniciar la aplicación y, después, deje que popstate gestione las navegaciones posteriores. Sin esto, la página inicial queda en blanco cuando la primera navegación hacia atrás llega a ella.

En el enrutamiento basado exclusivamente en hash (URL como /#/about), el evento hashchange se dispara cuando cambia el hash. popstate también se dispara cuando cambian las rutas. Las SPA modernas usan la History API y popstate; el enrutamiento mediante hash es una opción heredada.

Para hacer que un clic normal en <a> active la navegación del lado del cliente, intercepte el clic, llame a preventDefault y después a pushState + renderPage. Compruebe las teclas modificadoras (Cmd/Ctrl al hacer clic para abrir una pestaña nueva) y déjelas pasar al comportamiento predeterminado.

Los navegadores intentan restaurar automáticamente la posición de desplazamiento al navegar hacia atrás, pero esto no es fiable en las SPA porque el contenido se renderiza de forma asíncrona. Guarde la posición de desplazamiento en el estado de pushState y restáurela en popstate: window.scrollTo(0, e.state?.scroll ?? 0).

Si renderPage obtiene datos de forma asíncrona, la URL se actualiza antes de que llegue el contenido. Muestre un estado de carga y después renderice la vista. Evite las condiciones de carrera en las que el usuario pulsa el botón de retroceso durante una solicitud y el resultado de la solicitud cancelada sobrescribe la vista nueva.

Los enrutadores de React Router, Vue Router y SvelteKit envuelven History + popstate. Incluso sin un framework, la primitiva subyacente es la misma: escuche popstate, intercepte los enlaces y llame a pushState. Puede crear su propio enrutador con unas ~50 líneas de JavaScript vanilla cuando la sobrecarga sea importante.

La configuración de cada vista puede añadir listeners de eventos y temporizadores. Sin una limpieza explícita cuando cambia la vista (en popstate o en el envoltorio de pushState), los listeners se acumulan y degradan el rendimiento con el tiempo. Realice el seguimiento de las suscripciones de cada vista con un AbortController y abórtelas cuando cambie la vista.

¿Por qué el evento popstate NO se dispara cuando llama por su cuenta a history.pushState?

popstate se dispara al navegar hacia atrás o hacia delante con el navegador y proporciona acceso al estado guardado y a la nueva ubicación. No se dispara con pushState/replaceState (su código ya lo sabe) ni durante la carga inicial de la página (debe renderizarla manualmente). Intercepte los clics en los enlaces para la navegación de la SPA, guarde la posición de desplazamiento en el estado y elimine los listeners cuando cambie la vista para evitar fugas.