From 074785cea106179cb3305637055ab0a009ca74f2 Mon Sep 17 00:00:00 2001 From: Peter Bengtsson Date: Tue, 8 Dec 2020 14:42:52 -0500 Subject: initial commit --- files/ru/web/api/history_api/index.html | 119 +++++++++++++++++++ .../working_with_the_history_api/index.html | 129 +++++++++++++++++++++ 2 files changed, 248 insertions(+) create mode 100644 files/ru/web/api/history_api/index.html create mode 100644 files/ru/web/api/history_api/working_with_the_history_api/index.html (limited to 'files/ru/web/api/history_api') diff --git a/files/ru/web/api/history_api/index.html b/files/ru/web/api/history_api/index.html new file mode 100644 index 0000000000..2238486e34 --- /dev/null +++ b/files/ru/web/api/history_api/index.html @@ -0,0 +1,119 @@ +--- +title: History API +slug: Web/API/History_API +tags: + - API + - DOM + - HTML5 + - История +translation_of: Web/API/History_API +--- +

{{DefaultAPISidebar("History API")}}
+ DOM-объект {{DOMxRef("Window")}} предоставляет доступ к истории текущей сессии браузера (не путать с историей браузерных расширений) через объект {{DOMxRef("Window.history","history")}}. Он предоставляет полезные методы и свойства, которые позволяют переходить назад и вперёд по истории пользователя и манипулировать её содержимым.

+ +

Понятия и использование

+ +

Перемещение назад и вперёд по истории пользователя выполняется с помощью методов {{DOMxRef("History.back","back()")}}, {{DOMxRef("History.forward","forward()")}}, и {{DOMxRef("History.go","go()")}}.

+ +

Перемещение вперёд и назад

+ +

Чтобы переместиться назад по истории:

+ +
window.history.back();
+
+ +

Данный метод работает так, будто пользователь нажал на кнопку "Назад" на панели браузера.
+ Похожим образом можно переместиться вперед (как если бы пользователь нажал на кнопку "Вперед"):

+ +
window.history.forward();
+
+ +

Перемещение к определённой странице в истории

+ +

Вы можете использовать метод {{DOMxRef("History.go","go()")}} для загрузки конкретной страницы из истории сессии, определяемой её позицией относительно текущей страницы. Относительная позиция текущей страницы равняется 0.

+ +

Вернуться на одну страницу назад (равноценно вызову {{DOMxRef("History.back","back()")}}):

+ +
window.history.go(-1);
+
+ +

Перейти на одну страницу вперёд (равноценно вызову {{DOMxRef("History.forward","forward()")}})

+ +
window.history.go(1);
+
+ +

По такому же принципу, можно перемещаться вперед на 2 страницы, передавая аргумент 2, и так далее.

+ +

Кроме того, метод go() можно использовать для обновления текущей страницы, передавая аргумент 0 или вызывая его без аргументов:

+ +
// Обе следующих инструкции обновляют текущую страницу
+window.history.go(0)
+window.history.go()
+ +

Узнать количество страниц, которые находятся в стеке истории, можно, получив значение свойства length:

+ +
var numberOfEntries = window.history.length;
+
+ +

Интерфейсы

+ +
+
{{domxref("History")}}
+
Позволяет манипулировать историей сессии браузера (то есть, страницами, посещёнными в той же закладке, что и текущая страница.
+
+ +

Примеры

+ +

В следующем примере свойству onpopstate назначается обработчик. А затем приводятся некоторые методы объекта истории для добавления, замени и перемещения по истории текущей вкладки браузера

+ +
window.onpopstate = function(event) {
+  alert(`location: ${document.location}, state: ${JSON.stringify(event.state)}`)
+}
+
+history.pushState({page: 1}, "title 1", "?page=1")
+history.pushState({page: 2}, "title 2", "?page=2")
+history.replaceState({page: 3}, "title 3", "?page=3")
+history.back() // alerts "location: http://example.com/example.html?page=1, state: {"page":1}"
+history.back() // alerts "location: http://example.com/example.html, state: null"
+history.go(2)  // alerts "location: http://example.com/example.html?page=3, state: {"page":3}"
+ +

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

+ + + + + + + + + + + + + + + + + + + +
СпецификацияСтатусКомментарий
{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}{{Spec2('HTML WHATWG')}}Нет изменений по сравнению с {{SpecName("HTML5 W3C")}}.
{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}{{Spec2('HTML5 W3C')}}Изначальное определение
+ +

Поддержка браузерами

+ +

{{Compat("api.History")}}

+ +

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

+ +

Справочники

+ + + +

Руководства

+ + diff --git a/files/ru/web/api/history_api/working_with_the_history_api/index.html b/files/ru/web/api/history_api/working_with_the_history_api/index.html new file mode 100644 index 0000000000..b1bf87726a --- /dev/null +++ b/files/ru/web/api/history_api/working_with_the_history_api/index.html @@ -0,0 +1,129 @@ +--- +title: Работа с History API +slug: Web/API/History_API/Working_with_the_History_API +translation_of: Web/API/History_API/Working_with_the_History_API +--- +

В HTML5 стали доступны методы {{DOMxRef("History.pushState","pushState()")}} и {{DOMxRef("History.replaceState","replaceState()")}} для добавления и изменения записей в истории. Эти методыработают в сочетании с событием {{domxref("Window.onpopstate","onpopstate")}}

+ +

Добавление и изменение записей в истории

+ +

{{ gecko_minversion_header("2") }}

+ +

{{DOMxRef("History.pushState","pushState()")}} позволяет изменить referrer, который используется в HTTP-заголовке для {{domxref("XMLHttpRequest")}} объектов, созданных после изменения состояния. Значением referrer будет URL документа, окно которого является this на момент создания {{domxref("XMLHttpRequest")}} объекта.

+ +

Пример метода pushState()

+ +

Предположим, на странице http://mozilla.org/foo.html выполняется следующий JavaScript-код:

+ +
let stateObj = {
+    foo: "bar",
+}
+
+history.pushState(stateObj, "page 2", "bar.html")
+
+ +

В результате этого в URL-строке отобразится адрес http://mozilla.org/bar.html, но браузер не будет загружать страницу bar.html и даже не будет проверять, существует ли она..

+ +

Теперь предположим, что пользователь перешел по адресу http://google.com и затем нажал на кнопку "Назад". В результате этого в URL будет отображаться http://mozilla.org/bar.html, а history.state будет содержать stateObj. Событие popstate не будет вызвано, поскольку страница была перезагружена. Сама страница будет выглядеть как bar.html.

+ +

Если пользователь ещё раз нажимает кнопку "Назад", URL изменится на http://mozilla.org/foo.html, а в документе снова произойдёт событие popstate, на этот раз с объектом состояния, имеющим значение null. В этом случае возврат назад также не меняет содержимое документа, как и на предыдущем шаге, хотя документ может сам обновить своё содержимое после получения события popstate.

+ +
+

Примечание: Вызов history.back() обычно ведёт себя так же, как нажатие на кнопку "Назад". Но есть одно важное исключение:

+ +

После использования history.pushState(), вызов history.back() не вызывает событие popstate. Нажатие в браузере на кнопку "Назад" (всё ещё) делает это.

+
+ +

Метод pushState()

+ +

Метод pushState() принимает три параметра: объект состояния, заголовок (в данный момент игнорируется) и (необязательно) параметр "URL".

+ +

Давайте более подробно рассмотрим каждый и этих трёх параметров.

+ +
+
state object 
+
Объект состояния – это JavaScript-объект, связанный с новой записью в истории, созданной pushState(). Всякий раз, когда пользователь переходит к новому состоянию, происходит событие popstate, а свойство state этого события содержит копию объекта состояния с записями истории.
+
Объект состояния может быть чем-угодно, что может быть сериализовано. Поскольку Firefox сохраняет объекты состояния на диске пользователя, чтобы их можно было восстановить после перезапуска браузера, мы накладываем ограничение в 640 тысяч символов на сериализованное представление объекта состояния. Если вы передаёте объект состояния, чьё сериализованное представление больше этого значения, метод pushState() выдаст исключение. Если вам нужно хранилище большего размера, следует рассмотреть использование sessionStorage и/или localStorage.
+
+ +
+
title
+
Заголовок - все браузеры, кроме Safari, на данный момент игнорируют этот параметр, но могут начать использовать в будущем. Ввиду будущих изменений метода, безопасным решением является передача пустой строки. В качестве альтернативы вы можете передать короткий заголовок для состояни, в которое переходите.
+
+ +
+
URL
+
Через этот параметр передаётся URL-адрес новой новый записи в истории. Обратите внимание, что браузер не будет пытаться загрузить данный URL сразу после вызова pushState(), но может попытаться сделать это позже, например, после того, как пользователь перезапустит браузер. Новый URL-адрес не обязан быть абсолютным; если он относительный, то определяется относительно текущего URL. Новый URL должен вести на тот же домен, протокол и порт, иначе pushState() выдаст исключение. Данный параметр не является обязательным; если он не указан, будет использоваться URL текущего документа.
+
+ +
Примечание: Начиная с Gecko 2.0 {{ geckoRelease("2.0") }} и до Gecko 5.0 {{ geckoRelease("5.0") }}, переданный объект сериализуется с помощью JSON. Начиная с Gecko 6.0 {{ geckoRelease("6.0") }}, объект сериализуется с помощью алгоритма структурированного клонирования. Это позволяет безопасно передавать более широкий спектр объектов.
+ +

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

+ +

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

+ + + +

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

+ +

В XUL-документах он создаёт указанный XUL-элемент

+ +

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

+ +

Метод replaceState()

+ +

history.replaceState() работает точно так же, как history.pushState(), за исключением того, что replaceState() изменяет текущую запись истории вместо создания новой записи. Обратите внимание, что он не предотвращает создание новой записи в глобальной истории браузера.

+ +

replaceState() особенно полезен, когда вы хотите обновить объект состояния или URL текущей записи в истории в ответ на какое-то действие пользователя.

+ +
+
+ +
Примечание: Начиная с Gecko 2.0 {{ geckoRelease("2.0") }} и до Gecko 5.0 {{ geckoRelease("5.0") }}, переданный объект сериализуется с помощью JSON. Начиная с Gecko 6.0 {{ geckoRelease("6.0") }}, объект сериализуется с помощью алгоритма структурированного клонирования. Это позволяет безопасно передавать более широкий спектр объектов.
+ +

Пример метода replaceState()

+ +

Предположим, на странице http://mozilla.org/foo.html выполняется следующий JavaScript-код:

+ +
let stateObj = { foo: "bar" }
+history.pushState(stateObj, "page 2", "bar.html")
+
+ +

Объяснение этих двух строк можно найти в приведённом выше разделе пример метода pushState().

+ +

Далее, предположим, на странице http://mozilla.org/bar.html выполняется JavaScript-код:

+ +
history.replaceState(stateObj, "page 3", "bar2.html")
+
+ +

Это приведёт к тому, что в URL-строке отобразится адрес http://mozilla.org/bar2.html, но браузер не станет сразу загружать bar2.html и даже не станет проверять наличие этой страницы bar2.html.

+ +

Теперь предположим, что пользователь переходит по адресу http://www.microsoft.com, а затем нажимает на кнопку "Назад". В этом случае в URL-строке отобразится http://mozilla.org/bar2.html. Если же пользователь снова нажмёт на кнопку "Назад", в URL-строке отобразится http://mozilla.org/foo.html и полностью обойдёт bar.html.

+ +

Событие popstate

+ +

Событие popstate вызывается в окне каждый раз, когда активная запись в истории меняется. Если запись в истории, которая активируется, была создана с помощью вызова {{DOMxRef("History.pushState","pushState")}} или активирована вызовом {{DOMxRef("History.replaceState","replaceState")}}, свойство state события popstate содержит копию записи в истории объекта события.

+ +

Примеры использования можно посмотреть в {{ domxref("Window.onpopstate") }}.

+ +

Чтение текущего состояния

+ +

Когда страница загружается, она может иметь объект события со значением, отличным от "null". Это может произойти, например, если страница устанавливает объект состояния (с помощью {{DOMxRef("History.pushState","pushState()")}} или {{DOMxRef("History.replaceState","replaceState()")}}) и затем пользователь перезапускает браузер. Когда страница перезагружается, она получит событие onload, но не получит событие popstate. Тем не менее, если вы прочитаете свойство {{DOMxRef("History.state","history.state")}}, получите объект состояния, который получили, если бы произошло событие popstate.

+ +

С помощью свойства {{DOMxRef("History.state","history.state")}} можно прочитать состояние текущей записи в истории, не дожидаясь события popstate, например:

+ +
let currentState = history.state
+
+ +

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

+ + -- cgit v1.2.3-54-g00ecf