¿Qué es la API History?

¿Qué es la API History?

La API History (API de historial del navegador) es una interfaz, expuesta como window.history, que permite a JavaScript moverse por el historial de la sesión y añadir o modificar entradas. Con pushState() y replaceState() una página puede actualizar la barra de direcciones y el botón Atrás sin recargarse, y así una aplicación de una sola página da a cada pantalla su propia URL.

Cómo funciona

• history.back(), history.forward() y history.go(n) se mueven por las entradas existentes, como los botones del navegador. history.length es el número de entradas.
• history.pushState(state, "", url) añade una entrada nueva. history.replaceState(state, "", url) sobrescribe la actual.
• state es cualquier objeto serializable que se guarda con la entrada. El segundo argumento no se usa, pero no puede omitirse: pase una cadena vacía.
• url es opcional y debe tener el mismo origen que la página actual; si no, la llamada lanza un SecurityError.
• Ninguno de los dos métodos carga la URL ni comprueba que exista. Solo cambian lo que el navegador registra y muestra.
• El evento popstate se dispara cuando el usuario se mueve por el historial (Atrás, Adelante, go()). Llamar a pushState() o replaceState() no lo dispara, y los navegadores pueden omitirlo hasta que se haya interactuado con la página.

La referencia de MDN sobre pushState() documenta los detalles.

Un enrutador mínimo

La navegación llama a pushState y dibuja la vista por sí misma. Atrás y Adelante disparan popstate, y el manejador dibuja la vista de la URL que el navegador ha restaurado:

function navigate(path) {
  history.pushState({ path: path }, "", path);
  render(path);
}

window.addEventListener("popstate", function () {
  render(location.pathname);
});

El renderizado trabaja sobre el DOM existente, así que no se solicita ningún documento nuevo.

El servidor sigue teniendo que responder a esas URL

Una URL creada con pushState es solo un registro en el navegador. Si un visitante recarga en /products/42, la guarda como favorito o sigue un enlace compartido, el servidor recibe esa petición. Debe devolver la aplicación (o contenido real), no un 404. Según MDN, el navegador no carga la URL tras pushState(), pero puede cargarla más tarde, por ejemplo tras reiniciarse.

SEO y rastreadores

La recomendación de Google para sitios con JavaScript es usar la API History para el enrutamiento entre vistas y no usar fragmentos de URL para cargar contenido distinto. Los enlaces deben ser elementos <a href="..."> reales: los rastreadores encuentran enlaces a través del href, y un manejador de clic en un span o un ancla sin href no les da nada que seguir. Las vistas de error también requieren cuidado: una página 404 enrutada en el cliente sigue devolviendo estado 200 salvo que redirija a una URL que devuelva un 404 real o añada una etiqueta robots noindex. Véanse los fundamentos de SEO con JavaScript de Google.

Errores comunes

• Sin manejador de popstate. La URL cambia al pulsar Atrás, pero la pantalla no.
• Enlaces sin href. Funcionan en el navegador y son invisibles para los rastreadores; fallan el clic central y "abrir en pestaña nueva".
• Enrutamiento con hash para el contenido. Los rastreadores no resuelven de forma fiable las URL con fragmento.
• Objetos de estado grandes. Algunos navegadores limitan el tamaño serializado y lanzan un error. Mantenga el estado pequeño y use sessionStorage para más.
• Esperar que cambie el título. El segundo argumento se ignora: asigne document.title usted mismo y mueva el foco para quienes usan lector de pantalla.
• Sin respaldo en el servidor. Los enlaces profundos devuelven 404 al recargar.

Relación con las pruebas y la monitorización

Una navegación con pushState normalmente no solicita una página HTML nueva. El coste está en las llamadas a la API y el renderizado posteriores, así que una prueba que solo descarga HTML se pierde casi todo. Pruebe las llamadas a la API que hace la aplicación, ponderadas como las hacen los usuarios: véase pruebas de carga de aplicaciones de una sola página, que se ejecutan con las pruebas de carga. La monitorización de API sigue vigilando los endpoints que hay detrás de sus rutas, y la monitorización sintética cubre recorridos completos. Compruebe también las URL profundas directamente: una petición a la URL de una ruta debe devolver 200 desde el servidor, no funcionar solo tras navegar dentro de la aplicación.

Preguntas frecuentes: API History

¿pushState recarga la página?

No. Añade una entrada al historial y cambia la URL de la barra de direcciones, pero el navegador no carga esa URL ni comprueba que exista.

¿pushState dispara el evento popstate?

No. popstate se dispara cuando cambia la entrada activa del historial por navegación del usuario, como Atrás, Adelante o history.go(). Tras su propia llamada a pushState, actualiza usted la vista.

¿Qué diferencia hay entre pushState y replaceState?

pushState añade una entrada nueva, así que Atrás vuelve a la anterior. replaceState sobrescribe la actual, por lo que no se crea un paso extra de Atrás. Use replace para correcciones como redirecciones o para actualizar un filtro en la URL.

¿Enrutamiento con hash o API History?

Para contenido que deba indexarse, use la API History con rutas reales. Google desaconseja usar fragmentos de URL para cargar contenido distinto. El enrutamiento con hash no necesita configuración del servidor, lo que puede servir para herramientas internas sin tráfico de búsqueda.

¿Necesito configurar el servidor para las rutas de la API History?

Sí. El servidor debe responder a cada URL de ruta, normalmente devolviendo el esqueleto de la aplicación o contenido prerenderizado, porque una recarga, un favorito o un enlace compartido piden esa URL directamente.