initial commit

2 files changed, 248 insertions, 0 deletions

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
+---
+<p>{{DefaultAPISidebar("History API")}}<br>
+ DOM-объект {{DOMxRef("Window")}} предоставляет доступ к истории текущей сессии браузера (не путать с <a href="https://wiki.developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/history">историей браузерных расширений</a>) через объект {{DOMxRef("Window.history","history")}}. Он предоставляет полезные методы и свойства, которые позволяют переходить назад и вперёд по истории пользователя и манипулировать её содержимым.</p>
+
+<h2 id="Понятия_и_использование">Понятия и использование</h2>
+
+<p>Перемещение назад и вперёд по истории пользователя выполняется с помощью методов {{DOMxRef("History.back","back()")}}, {{DOMxRef("History.forward","forward()")}}, и {{DOMxRef("History.go","go()")}}.</p>
+
+<h3 id="Перемещение_вперёд_и_назад">Перемещение вперёд и назад</h3>
+
+<p>Чтобы переместиться назад по истории:</p>
+
+<pre class="brush: js notranslate">window.history.back();
+</pre>
+
+<p>Данный метод работает так, будто пользователь нажал на кнопку "Назад" на панели браузера.<br>
+ Похожим образом можно переместиться вперед (как если бы пользователь нажал на кнопку "Вперед"):</p>
+
+<pre class="brush: js notranslate">window.history.forward();
+</pre>
+
+<h3 id="Перемещение_к_определённой_странице_в_истории">Перемещение к определённой странице в истории</h3>
+
+<p>Вы можете использовать метод {{DOMxRef("History.go","go()")}} для загрузки конкретной страницы из истории сессии, определяемой её позицией относительно текущей страницы. Относительная позиция текущей страницы равняется <code>0</code>.</p>
+
+<p>Вернуться на одну страницу назад (равноценно вызову {{DOMxRef("History.back","back()")}}):</p>
+
+<pre class="brush: js notranslate">window.history.go(-1);
+</pre>
+
+<p>Перейти на одну страницу вперёд (равноценно вызову {{DOMxRef("History.forward","forward()")}})</p>
+
+<pre class="brush: js notranslate">window.history.go(1);
+</pre>
+
+<p>По такому же принципу, можно перемещаться вперед на 2 страницы, передавая аргумент <code>2</code>, и так далее.</p>
+
+<p>Кроме того, метод <code>go()</code> можно использовать для обновления текущей страницы, передавая аргумент <code>0</code> или вызывая его без аргументов:</p>
+
+<pre class="notranslate">// Обе следующих инструкции обновляют текущую страницу
+window.history.go(0)
+window.history.go()</pre>
+
+<p>Узнать количество страниц, которые находятся в стеке истории, можно, получив значение свойства <code>length</code>:</p>
+
+<pre class="brush: js notranslate">var numberOfEntries = window.history.length;
+</pre>
+
+<h2 id="Интерфейсы">Интерфейсы</h2>
+
+<dl>
+ <dt>{{domxref("History")}}</dt>
+ <dd>Позволяет манипулировать историей сессии браузера (то есть, страницами, посещёнными в той же закладке, что и текущая страница.</dd>
+</dl>
+
+<h2 id="Примеры">Примеры</h2>
+
+<p>В следующем примере свойству <code>onpopstate</code> назначается обработчик. А затем приводятся некоторые методы объекта истории для добавления, замени и перемещения по истории текущей вкладки браузера</p>
+
+<pre class="notranslate">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}"</pre>
+
+<h2 id="Спецификации">Спецификации</h2>
+
+<table class="standard-table">
+ <tbody>
+  <tr>
+   <th scope="col">Спецификация</th>
+   <th scope="col">Статус</th>
+   <th scope="col">Комментарий</th>
+  </tr>
+  <tr>
+   <td>{{SpecName('HTML WHATWG', "browsers.html#history", "History")}}</td>
+   <td>{{Spec2('HTML WHATWG')}}</td>
+   <td>Нет изменений по сравнению с {{SpecName("HTML5 W3C")}}.</td>
+  </tr>
+  <tr>
+   <td>{{SpecName('HTML5 W3C', "browsers.html#history", "History")}}</td>
+   <td>{{Spec2('HTML5 W3C')}}</td>
+   <td>Изначальное определение</td>
+  </tr>
+ </tbody>
+</table>
+
+<h2 id="Поддержка_браузерами">Поддержка браузерами</h2>
+
+<p>{{Compat("api.History")}}</p>
+
+<h2 id="Смотрите_также">Смотрите также</h2>
+
+<h3 id="Справочники">Справочники</h3>
+
+<ul>
+ <li>{{ domxref("window.history") }}</li>
+ <li>{{ domxref("window.onpopstate") }}</li>
+</ul>
+
+<h3 id="Руководства">Руководства</h3>
+
+<ul>
+ <li><a href="https://wiki.developer.mozilla.org/en-US/docs/Web/API/History_API/Working_with_the_History_API">Working with the History API</a></li>
+</ul>
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
+---
+<p>В HTML5 стали доступны методы {{DOMxRef("History.pushState","pushState()")}} и {{DOMxRef("History.replaceState","replaceState()")}} для добавления и изменения записей в истории. Эти методыработают в сочетании с событием {{domxref("Window.onpopstate","onpopstate")}}</p>
+
+<h2 id="Добавление_и_изменение_записей_в_истории">Добавление и изменение записей в истории</h2>
+
+<p>{{ gecko_minversion_header("2") }}</p>
+
+<p>{{DOMxRef("History.pushState","pushState()")}} позволяет изменить referrer, который используется в HTTP-заголовке для {{domxref("XMLHttpRequest")}} объектов, созданных после изменения состояния. Значением referrer будет URL документа, окно которого является <code>this</code> на момент создания {{domxref("XMLHttpRequest")}} объекта.</p>
+
+<h3 id="Пример_метода_pushState">Пример метода pushState()</h3>
+
+<p>Предположим, на странице <code>http://mozilla.org/foo.html</code> выполняется следующий JavaScript-код:</p>
+
+<pre class="brush: js notranslate">let stateObj = {
+    foo: "bar",
+}
+
+history.pushState(stateObj, "page 2", "bar.html")
+</pre>
+
+<p>В результате этого в URL-строке отобразится адрес <code>http://mozilla.org/bar.html</code>, но браузер не будет загружать страницу <code>bar.html</code> и даже не будет проверять, существует ли она..</p>
+
+<p>Теперь предположим, что пользователь перешел по адресу <code>http://google.com</code> и затем нажал на кнопку "<strong>Назад</strong>". В результате этого в URL будет отображаться <code>http://mozilla.org/bar.html</code>, а <code>history.state</code> будет содержать <code>stateObj</code>. Событие popstate не будет вызвано, поскольку страница была перезагружена. Сама страница будет выглядеть как <code>bar.html</code>.</p>
+
+<p>Если пользователь ещё раз нажимает кнопку <strong>"Назад"</strong>, URL изменится на <code>http://mozilla.org/foo.html</code>, а в документе снова произойдёт событие <code>popstate</code>, на этот раз с объектом состояния, имеющим значение <code>null</code>. В этом случае возврат назад также не меняет содержимое документа, как и на предыдущем шаге, хотя документ может сам обновить своё содержимое после получения события <code>popstate</code>.</p>
+
+<div class="blockIndicator note">
+<p><strong>Примечание:</strong> Вызов <code>history.back()</code> обычно ведёт себя так же, как нажатие на кнопку <strong>"Назад"</strong>. Но есть одно важное исключение:</p>
+
+<p><em>После использования</em> <code>history.pushState()</code>, вызов <code>history.back()</code> <em>не вызывает событие</em> <code>popstate</code>. Нажатие в браузере на кнопку "Назад" (всё ещё) делает это.</p>
+</div>
+
+<h3 id="Метод_pushState">Метод pushState()</h3>
+
+<p>Метод <code>pushState()</code> принимает три параметра: <em>объект состояния</em>, <em>заголовок</em> (в данный момент игнорируется) и (необязательно) параметр "<em>URL"</em>.</p>
+
+<p>Давайте более подробно рассмотрим каждый и этих трёх параметров.</p>
+
+<dl>
+ <dt><strong>state object</strong> </dt>
+ <dd>Объект состояния – это JavaScript-объект, связанный с новой записью в истории, созданной <code>pushState()</code>. Всякий раз, когда пользователь переходит к новому состоянию, происходит событие <code>popstate</code>, а свойство <code>state</code> этого события содержит копию объекта состояния с записями истории.</dd>
+ <dd>Объект состояния может быть чем-угодно, что может быть сериализовано. Поскольку Firefox сохраняет объекты состояния на диске пользователя, чтобы их можно было восстановить после перезапуска браузера, мы накладываем ограничение в 640 тысяч символов на сериализованное представление объекта состояния. Если вы передаёте объект состояния, чьё сериализованное представление больше этого значения, метод <code>pushState()</code> выдаст исключение. Если вам нужно хранилище большего размера, следует рассмотреть использование <code>sessionStorage</code> и/или <code>localStorage</code>.</dd>
+</dl>
+
+<dl>
+ <dt><strong>title</strong></dt>
+ <dd>Заголовок - <a href="https://github.com/whatwg/html/issues/2174">все браузеры, кроме Safari, на данный момент игнорируют этот параметр</a>, но могут начать использовать в будущем. Ввиду будущих изменений метода, безопасным решением является передача пустой строки. В качестве альтернативы вы можете передать короткий заголовок для состояни, в которое переходите.</dd>
+</dl>
+
+<dl>
+ <dt><strong>URL</strong></dt>
+ <dd>Через этот параметр передаётся URL-адрес новой новый записи в истории. Обратите внимание, что браузер не будет пытаться загрузить данный URL сразу после вызова <code>pushState()</code>, но может попытаться сделать это позже, например, после того, как пользователь перезапустит браузер. Новый URL-адрес не обязан быть абсолютным; если он относительный, то определяется относительно текущего URL. Новый URL должен вести на тот же домен, протокол и порт, иначе <code>pushState()</code> выдаст исключение. Данный параметр не является обязательным; если он не указан, будет использоваться URL текущего документа.</dd>
+</dl>
+
+<div class="note"><strong>Примечание:</strong> Начиная с Gecko 2.0 {{ geckoRelease("2.0") }} и до Gecko 5.0 {{ geckoRelease("5.0") }}, переданный объект сериализуется с помощью JSON. Начиная с Gecko 6.0 {{ geckoRelease("6.0") }}, объект сериализуется с помощью <a href="/en/DOM/The_structured_clone_algorithm">алгоритма структурированного клонирования</a>. Это позволяет безопасно передавать более широкий спектр объектов.</div>
+
+<p>Вызов <code>pushState()</code> в некоторой степени похож на установку <code>window.location = "#foo"</code>, поскольку они оба также создают и активируют ещё одну запись в истории, связанную с текущим документом.</p>
+
+<p>Но у <code>pushState()</code> есть несколько преимуществ:</p>
+
+<ul>
+ <li>Новый URL может быть любым в пределах того же домена, порта и протокола, что и текущий адрес. Тогда как настройка <code>window.location</code> оставляет вас на том же {{ domxref("document") }} лишь в том случае, если вы меняете только хэш</li>
+ <li>Менять URL не обязательно. Тогда как настройка <code>window.location = "#foo";</code> создаёт новую запись в истории, только если текущий хеш не <code>#foo</code></li>
+ <li>С новой записью в истории можно связать любые данные. В подходе, основанном на хеше, все соответствующие данные нужно кодировать в короткую строку</li>
+ <li>Если заголовок <code>title</code> впоследствии используется браузерами, эти данные могут быть использованы (независимо от, скажем, хеша).</li>
+</ul>
+
+<p>Обратите внимание, что <code>pushState()</code> никогда не вызывает событие <code>hashchange</code>, даже если новый URL отличается от старого только хешем.</p>
+
+<p>В <a href="/en-US/docs/Mozilla/Tech/XUL">XUL</a>-документах он создаёт указанный XUL-элемент</p>
+
+<p>В других документах он создаёт элемент с null namespace URI.</p>
+
+<h3 id="Метод_replaceState">Метод replaceState()</h3>
+
+<p><code>history.replaceState()</code> работает точно так же, как <code>history.pushState()</code>, за исключением того, что <code>replaceState()</code> изменяет текущую запись истории вместо создания новой записи. Обратите внимание, что он не предотвращает создание новой записи в глобальной истории браузера.</p>
+
+<p><code>replaceState()</code> особенно полезен, когда вы хотите обновить объект состояния или URL текущей записи в истории в ответ на какое-то действие пользователя.</p>
+
+<dl>
+</dl>
+
+<div class="note"><strong>Примечание:</strong> Начиная с Gecko 2.0 {{ geckoRelease("2.0") }} и до Gecko 5.0 {{ geckoRelease("5.0") }}, переданный объект сериализуется с помощью JSON. Начиная с Gecko 6.0 {{ geckoRelease("6.0") }}, объект сериализуется с помощью <a href="/en/DOM/The_structured_clone_algorithm">алгоритма структурированного клонирования</a>. Это позволяет безопасно передавать более широкий спектр объектов.</div>
+
+<h3 id="Пример_метода_replaceState">Пример метода replaceState()</h3>
+
+<p>Предположим, на странице <code><span class="nowiki">http://mozilla.org/foo.html</span></code> выполняется следующий JavaScript-код:</p>
+
+<pre class="brush: js notranslate">let stateObj = { foo: "bar" }
+history.pushState(stateObj, "page 2", "bar.html")
+</pre>
+
+<p>Объяснение этих двух строк можно найти в приведённом выше разделе <em><a href="#Example_of_pushState_method">пример метода pushState()</a></em>.</p>
+
+<p>Далее, предположим, на странице <code><span class="nowiki">http://mozilla.org/bar.html</span></code><span class="nowiki"> выполняется JavaScript-код:</span></p>
+
+<pre class="brush: js notranslate">history.replaceState(stateObj, "page 3", "bar2.html")
+</pre>
+
+<p>Это приведёт к тому, что в URL-строке отобразится адрес <code><span class="nowiki">http://mozilla.org/bar2.html</span></code><span class="nowiki">, но браузер не станет сразу загружать </span><code>bar2.html</code> и даже не станет проверять наличие этой страницы <code>bar2.html</code>.</p>
+
+<p>Теперь предположим, что пользователь переходит по адресу <code><span class="nowiki">http://www.microsoft.com</span></code><span class="nowiki">, а затем нажимает на кнопку <strong>"Назад"</strong>. В этом случае в URL-строке отобразится <code>http://mozilla.org/bar2.html</code>. Если же пользователь снова нажмёт на кнопку <strong>"Назад"</strong>, в URL-строке отобразится <code>http://mozilla.org/foo.html</code> и полностью обойдёт <code>bar.html</code>.</span></p>
+
+<h3 id="Событие_popstate">Событие popstate</h3>
+
+<p>Событие <code>popstate</code> вызывается в окне каждый раз, когда активная запись в истории меняется. Если запись в истории, которая активируется, была создана с помощью вызова {{DOMxRef("History.pushState","pushState")}} или активирована вызовом {{DOMxRef("History.replaceState","replaceState")}}, свойство <code>state</code> события <code>popstate</code> содержит копию записи в истории объекта события.</p>
+
+<p>Примеры использования можно посмотреть в {{ domxref("Window.onpopstate") }}.</p>
+
+<h3 id="Чтение_текущего_состояния">Чтение текущего состояния</h3>
+
+<p>Когда страница загружается, она может иметь объект события со значением, отличным от <code>"null"</code>. Это может произойти, например, если страница устанавливает объект состояния (с помощью {{DOMxRef("History.pushState","pushState()")}} или {{DOMxRef("History.replaceState","replaceState()")}}) и затем пользователь перезапускает браузер. Когда страница перезагружается, она получит событие <code>onload</code>, но не получит событие <code>popstate</code>. Тем не менее, если вы прочитаете свойство {{DOMxRef("History.state","history.state")}}, получите объект состояния, который получили, если бы произошло событие <code>popstate</code>.</p>
+
+<p>С помощью свойства {{DOMxRef("History.state","history.state")}} можно прочитать состояние текущей записи в истории, не дожидаясь события <code>popstate</code>, например:</p>
+
+<pre class="brush: js notranslate">let currentState = history.state
+</pre>
+
+<h2 id="Смотрите_также">Смотрите также</h2>
+
+<ul>
+ <li><a href="/en-US/docs/Web/API/History_API">History API</a></li>
+ <li><a href="/en-US/docs/Web/API/History_API/Example">Ajax navigation example</a></li>
+ <li>{{ domxref("window.history") }}</li>
+</ul>