History.pushState()

This translation is incomplete. Please help translate this article from English

En un documento HTML, el método history.pushState() anexa un registro en la sesión de historial del navegador.

Sintaxis

history.pushState(state, title, [url])

Parámetros

state
El objeto state es un objeto de JavaScript asociado al nuevo registro en el historial creado por pushState(). Cuando el usuario navega al nuevo registro, un evento popstate es accionado, y la propiedad state del evento contiene una copia del objeto state del registro en el historial.
El objeto state puede ser cualquier cosa que pueda ser serializada. Porque Firefox guarda los objetos  state en el disco del usuario para que así puedan ser restaurados luego de que el usuario reinicia el navegador, se impone un límite de 640k caracteres en la representación serializada de un objeto state. Si pasas un objeto state con una representación serializada más grande que lo mencionado, a pushState(), el método arrojará una excepción. Si necesitas más espacio que el mencionado, es recomendable que uses sessionStorage y/o localStorage.
title
La mayoría de los navegadores ignoran este parámetro, sin embargo, podrían usarlo en el futuro. Pasar una cadena de texto vacía aquí, debería ser seguro contra futuros cambios en el método. Alternativamente, podrías pasar un título corto por el estado al cual te estás moviendo. Si necesitas que el título sea modificado, puedes usar document.title.
url Optional
La URL del nuevo registro en el historial, se define en este parámetro. Es importante destacar que el navegador no intentará cargar esta URL luego de una llamada a pushState(), pero podría intentar cargar esta URL luego, por ejemplo, luego de que el usuario reinicie el navegador. La nueva URL no necesita ser absoluta; puede ser relativa a la URL actual. La nueva URL debe tener el mismo origin que la URL actual; de otra manera, pushState() arrojará una excepción. Si este parámetro no es especificado, por defecto se usa la URL del documento actual.

Descripción

En cierto sentido, llamar a pushState() es similar a window.location = "#foo", ambos crearán y activarán un nuevo registro en el historial asociado al documento actual. Pero pushState() tiene unas ventajas adicionales:

  • La nueva URL pueded ser cualquier URL con el mismo origen que la URL actual. En contraste, usar window.location te mantiene en el mismo documento únicamente si modificas el hash.
  • No tienes que cambiar la URL si no quieres. En contraste, usar window.location = "#foo"; sólo crea un nuevo registro en el historial si el hash actual no es #foo.
  • Puedes asociar datos arbitrarios a tu nuevo registro en el historial. Con el truco del hash, necesitas codificar todos los datos relevantes en una corta cadena de texto.

Cabe destacar que pushState() nunca hace que el evento hashchange sea accionado, incluso si la nueva URL difiere de la URL antigua sólo en su hash.

En otros documentos, crea u nelemento con una URI null.

Ejemplos

Esto crea un nuevo registro en el historial del navegador, estableciendo state, title, y url.

JavaScript

const state = { 'page_id': 1, 'user_id': 5 }
const title = ''
const url = 'hello-world.html'

history.pushState(state, title, url)

Especificaciones

Especificación Estado Comentario
HTML Living Standard
La definición de 'History.pushState()' en esta especificación.
Living Standard Ningún cambio desde HTML5.
HTML5
La definición de 'History.pushState()' en esta especificación.
Recommendation Definición Inicial.

Compatibilidad en Navegadores

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome para AndroidFirefox para AndroidOpera para AndroidSafari en iOSSamsung Internet
pushStateChrome Soporte completo 5Edge Soporte completo 12Firefox Soporte completo 4
Notas
Soporte completo 4
Notas
Notas Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
IE Soporte completo 10Opera Soporte completo 11.5Safari Soporte completo 5WebView Android Soporte completo ≤37Chrome Android Soporte completo 18Firefox Android Soporte completo 4
Notas
Soporte completo 4
Notas
Notas Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
Opera Android Soporte completo 11.5Safari iOS Soporte completo 4.3Samsung Internet Android Soporte completo 1.0
Whether the title argument is usedChrome Sin soporte NoEdge Sin soporte NoFirefox Sin soporte NoIE Sin soporte NoOpera Sin soporte NoSafari Soporte completo SiWebView Android Sin soporte NoChrome Android Sin soporte NoFirefox Android Sin soporte NoOpera Android Sin soporte NoSafari iOS ? Samsung Internet Android Sin soporte No

Leyenda

Soporte completo  
Soporte completo
Sin soporte  
Sin soporte
Compatibilidad desconocida  
Compatibilidad desconocida
Ver notas de implementación.
Ver notas de implementación.

Mira también