History.pushState()

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

Метод pushState() принимает 3 параметра: state, title (который в данный момент игнорируется), URL. Давайте рассмотрим каждый параметр подробнее:

  • State — JavaScript объект, который связан с новой записью в истории браузера, созданной при помощи pushState(). Всякий раз, когда пользователь перемещается на новое состояние истории браузера при помощи таких функций, как, например history.back() или history.go(), срабатывает событие popstate, а в объект event передаётся свойство state

    Объект state должен быть чем-то, что возможно сериализовать, т. к. Firefox сохраняет объект state на диске пользователя. В дальнейшем данные могут быть восстановлены даже после перезапуска браузера. Мы установили лимит в 640k символов на сериализованный объект state. Если вы передаёте объект state у которого сериализованное представление превышает 640k символов, метод pushState() вернёт ошибку. Если вам необходимо сохранить больший объем информации, рекомендуем воспользоваться sessionStorage и/или localStorage.

  • Title — в данный момент Firefox игнорирует данный параметр. Тем не менее аргумент может передаваться. Передача пустой строки вместо title должна быть безопасно с учётом будущих изменений метода. В качестве альтернативы можно передавать title в объекте state и использовать его оттуда.

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

Заметка: Начиная с Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) до Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), переданный объект сериализуется при помоши JSON. Начиная с Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), объект сериализуется используя the structured clone algorithm. Это позволяет сделать передачу объектов более безопасной.

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

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

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

В XUL документе это создаёт соответствующий XUL элемент.

В других документах это создаёт с нулевым значением URI.

Синтаксис

history.pushState(state, title, url);

Пример

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

JavaScript

var state = { 'page_id': 1, 'user_id': 5 };
var title = 'Hello World';
var url = 'hello-world.html';

history.pushState(state, title, url);

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

Спецификация Статус Комментарий
WHATWG HTML Living Standard
Определение 'History' в этой спецификации.
Живой стандарт Не изменён в HTML5.
HTML5
Определение 'History' в этой спецификации.
Рекомендация Начальное определение

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

Особенность Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Базовая поддержка (Да) (Да) (Да) (Да) (Да)
Особенность Android Android Webview Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Базовая поддержка (Да) (Да) (Да) (Да) (Да) (Да) (Да)

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

Метки документа и участники

Метки: 
 Внесли вклад в эту страницу: levyn, gorodilovyy, vyushin
 Обновлялась последний раз: levyn,