History.pushState()

В HTML документе метод history.pushState() добавляет новое состояние в историю браузера

Синтаксис

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

Параметры

state

Объект состояния – это JavaScript-объект, связанный с новой записью в истории, созданной pushState(). Всякий раз, когда пользователь переходит к новому состоянию, происходит событие popstate, а свойство state этого события содержит копию объекта состояния с записями истории.

Объект состояния может быть чем угодно, что может быть сериализовано. Поскольку Firefox сохраняет объекты состояния на диске пользователя, чтобы их можно было восстановить после перезапуска браузера, мы накладываем ограничение в 640 тысяч символов на сериализованное представление объекта состояния. Если вы передаёте объект состояния, чьё сериализованное представление больше этого значения, метод pushState() выдаст исключение. Если вам нужно хранилище большего размера, следует рассмотреть использование sessionStorage и/или localStorage.

title

Заголовок - все браузеры, кроме Safari, на данный момент игнорируют этот параметр, но могут начать использовать в будущем. Ввиду будущих изменений метода, безопасным решением является передача пустой строки. В качестве альтернативы вы можете передать короткий заголовок для состояния, в которое переходите.

url Необязательный

Через этот параметр передаётся URL-адрес новой записи в истории. Обратите внимание, что браузер не будет пытаться загрузить данный URL сразу после вызова pushState(), но может попытаться сделать это позже, например, после того, как пользователь перезапустит браузер. Новый URL-адрес не обязан быть абсолютным; если он относительный, то определяется относительно текущего URL. Новый URL должен вести на тот же домен, протокол и порт, иначе pushState() выдаст исключение. Данный параметр не является обязательным; если он не указан, будет использоваться URL текущего документа.

Описание

Вызов pushState() в некоторой степени похож на установку window.location = "#foo", поскольку они оба также создают и активируют ещё одну запись в истории, связанную с текущим документом.

Но у pushState() есть несколько преимуществ:

  • Новый URL может быть любым в пределах того же домена, порта и протокола, что и текущий адрес. Тогда как настройка window.location оставляет вас на том же document лишь в том случае, если вы меняете только хэш
  • Менять URL не обязательно. Тогда как настройка window.location = "#foo"; создаёт новую запись в истории, только если текущий хеш не #foo
  • С новой записью в истории можно связать любые данные. В подходе, основанном на хеше, все соответствующие данные нужно кодировать в короткую строку
  • Если заголовок title впоследствии используется браузерами, эти данные могут быть использованы (независимо от, скажем, хеша).

Обратите внимание, что pushState() никогда не вызывает событие hashchange, даже если новый URL отличается от старого только хешем.

Примеры

Создание новой записи истории браузера, задавая state, title, и url.

JavaScript

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

history.pushState(state, title, url)

Спецификации

Specification
HTML Standard
# dom-history-pushstate-dev

Совместимость с браузерами

BCD tables only load in the browser

Смотрите также