プログラミング

History API のメモ

投稿日:2019年2月13日 更新日:

History API についての簡単な説明を書きました。

「History API の概要を思い出したくなった時に、ざっと眺める」というのがこのページの主な目的です。

1. History API とは?

ウェブブラウザでウェブページを閲覧している際のページ遷移履歴を管理・操作するための API です。

参考

2. History インタフェースの定義

HTML Standard – 7.7.2 The History interface から引用

enum ScrollRestoration { "auto", "manual" };

[Exposed=Window]
interface History {
  readonly attribute unsigned long length;
  attribute ScrollRestoration scrollRestoration;
  readonly attribute any state;
  void go(optional long delta = 0);
  void back();
  void forward();
  void pushState(any data, DOMString title, optional USVString? url = null);
  void replaceState(any data, DOMString title, optional USVString? url = null);
};

3. 主なメソッドの説明

window.history.go( [ delta ] )

  • セッション履歴内の指定されたステップ数だけ前または後ろに進みます。
  • deltaがゼロの場合は現在のページをリロードします。
  • delta が範囲外の場合は、何もしません。

window.history.back()

  • セッション履歴内の1つ後ろ戻ります。
  • 後ろのページがなければ何もしません。

window.history.forward()

  • セッション履歴内の1つ次に進みます。
  • 次のページがなければ何もしません。

window.history.pushState(data, title [, url ] )

  • 「stateデータ」「タイトル」「URL(あれば)」をセッション履歴に追加します。
  • それに合わせて、セッション履歴内の位置が1つ進められます(現在位置が追加した履歴になります)。(ここで [戻る] 操作をすると、先程までのページに戻ります)
  • 引数にセットした url に移動するわけではありません
  • 第三引数の url は、 現在の URLと same origin でなければなりません。指定されなかった場合は現在のドキュメントの URL が設定されます。

window.history.replaceState(data, title [, url ] )

  • 「stateデータ」「タイトル」「URL(あれば)」で、セッション履歴の現在のエントリを更新します。
  • pushState() と異なり、 replaceState() は新しく履歴エントリを作成する代わりに現在の履歴エントリを修正します。

※ 主に HTML Standard – 7.7.2 The History interface の文章を翻訳しています。
※ 一部、ブラウザの履歴を操作する – ウェブデベロッパーガイド | MDN の文章も引用しています。

4. onpopstate イベントと移動系メソッドの動作例

popstate イベントは、同じ文書の2つの履歴項目の間で、アクティブな履歴項目が変わるたびにウィンドウに発行されます(引用元:WindowEventHandlers.onpopstate – Web API | MDN)。

WindowEventHandlers.onpopstate – Web API | MDN に載っているサンプルコードに説明を追加してみました。

window.onpopstate = function(event) {
  console.log("location: " + document.location + ", state: " + JSON.stringify(event.state));
};

// この時点の状態が (1) です

history.pushState({page: 1}, "title 1", "?page=1"); // (2) 履歴が1つ進む
history.pushState({page: 2}, "title 2", "?page=2"); // (3) 履歴が1つ進む
history.replaceState({page: 3}, "title 3", "?page=3"); // (4) 現在の履歴が入れ替わる
history.back(); // (5) alerts "location: http://example.com/example.html?page=1, state: {"page":1}"
history.back(); // (6) alerts "location: http://example.com/example.html, state: null
history.go(2);  // (7) alerts "location: http://example.com/example.html?page=3, state: {"page":3}

この時の履歴の状態変化を以下に示します。

(1) [最初のページ]
         
(2) [最初のページ] → [title 1]
                        
(3) [最初のページ] → [title 1] → [title 2]
                                     
(4) [最初のページ] → [title 1] → [title 3]
                                     
(5) [最初のページ] → [title 1] → [title 3]
                        
(6) [最初のページ] → [title 1] → [title 3]
         
(6) [最初のページ] → [title 1] → [title 3]
                                     
  • 最初のコードのコメントに入れてある (1) から (6) に対応しています。
  • 上矢印 () が現在いるページです。

📂-プログラミング

執筆者:labo


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

Web Programming

Webプログラミングのためのリンク集

Webプログラミングのためのリンク集です。

プログラミング

Rubyのように書け、Cのように速いプログラム言語 Crystal の基本的な使い方

Crystal というプログラミング言語の基本的な使い方について紹介します。 実際に「使ってみたい」「試してみたい」といった方に向けて、コードを書き始めるまでの導入方法について書きました。文法の説明な …

Web Components

Web Components の Slot について

Web Components の Slot について説明します。

web development

Resource Timing API を使って、リソースの読み込みに掛かった時間を計測する

目次1. Resource Timing API について2. サンプルコード3. PerformanceResourceTiming インターフェイス4. デモページ5. 参考仕様MDNブラウザの対 …

JavaScript

JavaScript で URL を扱う場合の処理

JavaScript で URL文字列に関する処理を行う場合、セキュリティの観点から、URL()コンストラクタを使うことが推奨されます。URL()コンストラクタによって URLオブジェクトを生成し、そ …