История: метод pushState()

Базовая Широко поддерживается

Эта функция хорошо зарекомендовала себя и работает на многих устройствах и версиях браузеров. Она доступна в браузерах с июля 2015 года.

Метод pushState() интерфейса History добавляет запись в стек истории браузера.

Синтаксис

pushState(state, unused)
pushState(state, unused, url)

Параметры

state

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

Объект state может быть любым сериализуемым объектом.

Примечание: Некоторые браузеры сохраняют объекты state на диске пользователя для восстановления после перезагрузки браузера, и устанавливают ограничение на размер сериализованного представления объекта state. Если вы передадите объект state, размер сериализованного представления которого превышает это ограничение, будет выброшено исключение. В случаях, когда требуется больше места, чем предоставляют некоторые браузеры, рекомендуется использовать sessionStorage и/или localStorage.

unused

Этот параметр существует по историческим причинам и не может быть опущен; передача пустой строки безопасна в отношении будущих изменений метода.

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

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

Возвращаемое значение

Ничего (undefined).

Исключения

SecurityError DOMException: Выбрасывается, если связанный документ не полностью активен или предоставленный параметр url не является допустимым URL. Браузеры также ограничивают навигацию и могут выбросить это исключение, сгенерировать предупреждение или проигнорировать вызов, если он вызывается слишком часто.
DataCloneError DOMException: Выбрасывается, если предоставленный параметр state не является сериализуемым.

Описание

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

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

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

Примеры

Это создает новую запись в истории браузера, устанавливая state и url.

JavaScript

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

history.pushState(state, "", url);

Изменение параметра запроса

const url = new URL(location);
url.searchParams.set("foo", "bar");
history.pushState({}, "", url);

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

Спецификация
HTML # dom-history-pushstate-dev

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

	Рабочие столы					Мобильные устройства
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox для Android	Opera Android	Safari на iOS	Samsung Internet	WebView Android
`pushState`	5	12	4 До Firefox 5 переданный объект сериализовался с помощью JSON. Начиная с Firefox 6, объект сериализуется с помощью алгоритма структурированного клонирования. Это позволяет безопасно передавать более широкий спектр объектов.	11.5	5	18	4 До Firefox для Android 5 переданный объект сериализовался с помощью JSON. Начиная с Firefox для Android 6, объект сериализуется с помощью алгоритма структурированного клонирования. Это позволяет безопасно передавать более широкий спектр объектов.	11.5	4	1.0	≤37
`unused_parameter`	Нет	Нет	Нет	Нет	5 Эта функция может быть удалена, см. баг 223190.	Нет	Нет	Нет	4 Эта функция может быть удалена, см. баг 223190.	Нет	Нет

См. также

© 2005–2024 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/History/pushState