Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

history.pushState() — una entrada del historial sin recargar

history.pushState() normalmente añade una entrada al historial de la sesión, guarda un estado y cambia la URL de forma opcional sin cargar un documento nuevo. La actualización de la interfaz queda a tu cargo.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

history.pushState(state, unused[, url]);

history.pushState() es una API del navegador definida por HTML, no por ECMAScript; los motores actuales de los navegadores la admiten. Que Node 24 esté disponible no demuestra que esta API también lo esté. El método normalmente añade una entrada al historial de la sesión, pero en un documento about:blank inicial sustituye la entrada actual en vez de añadir una nueva. En ambos casos devuelve undefined sin cargar un documento nuevo. En cambio, history.replaceState() actualiza la entrada actual sin añadir otra.

state se serializa, no se conserva como referencia; puedes leerlo mediante history.state. Las funciones no se pueden guardar de esta forma y provocan DataCloneError. El parámetro obligatorio unused suele recibir ''; no establece el título de la página.

La url opcional puede ser relativa; si se omite, la dirección no cambia. En páginas HTTP(S), debe conservar el mismo origen: esquema, host y puerto. Una URL no permitida, un documento que no esté completamente activo o las llamadas demasiado frecuentes pueden provocar SecurityError.

La llamada no dispara ni popstate ni hashchange, aunque cambie el fragmento. Actualiza la interfaz por tu cuenta; para la navegación Atrás/Adelante, gestiona popstate y event.state. El ejemplo muestra que cambiar posteriormente el objeto de entrada no modifica el estado almacenado.

Ejemplos

(() => {
  const state = { page: 2 };
  const url = new URL(location.href);
  url.hash = 'cktis-page-2';

  const result = history.pushState(state, '', url.href);
  state.page = 99;

  console.log(JSON.stringify({
    page: history.state.page,
    hash: location.hash,
    returnsUndefined: result === undefined
  }));
})();

Resultado

{"page":2,"hash":"#cktis-page-2","returnsUndefined":true}

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes