履歴 API
Baseline
広く利用可能
この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2015年7月以降、すべてのブラウザーで利用可能です。
履歴 API は、ブラウザーのセッション履歴 (WebExtensions history と混同しないように) へのアクセスをグローバルの history オブジェクトを介して提供しています。このオブジェクトは、ユーザーの履歴の中を前のページや後のページへ移動したり、履歴スタックの中を操作したりするのに便利なメソッドやプロパティが提供されています。
概念と使用方法
ユーザーの履歴の中を前のページや次のページへ移動するには、 back(), forward(), go() の各メソッドを使用します。
前のページや次のページへの移動
履歴を前に遡るには、次のようにします。
history.back();
これは、ちょうどユーザーがブラウザーのツールバーの戻るボタンをクリックしたときのような動作です。
同様に、次のようにして (ユーザーが次へボタンをクリックしたときのように) 次のページへ進むこともできます。
history.forward();
履歴内の特定の位置まで移動
go() メソッドを使うと、セッション履歴において現在のページから相対的な位置を指定して特定のページを読み込むことができます。 (現在のページの相対位置は 0 となります。)
ひとつ前のページへと戻る例です (back() と同様の動き)。
history.go(-1);
ページを進める例で、 forward() を呼び出すのと同様です。
history.go(1);
同様に、 2 を渡すことで 2 ページ分を進めることができます。
go() メソッドの他の使い方として、 0 を渡すか、引数なしで呼び出すことで、現在のページを再読み込みすることができます。
// 以下の文は、
// どちらもページを再読み込みする
// 効果があります。
history.go(0);
history.go();
length プロパティの値を参照することにより、履歴スタック中のページの数を知ることができます。
const numberOfEntries = history.length;
インターフェイス
History-
ブラウザーのセッション履歴（すなわち、現在のページが読み込まれているタブやフレームで表示したことがあるページ群）の操作ができます。
PopStateEvent-
popstateイベントのインターフェイスです。
例
以下の例では popstate イベントのリスナーを割り当てています。 history オブジェクトのメソッドで現在のタブのブラウザー履歴の追加、置換、移動など、いくつかの操作を説明しています。
window.addEventListener("popstate", (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}"
仕様書
| 仕様書 |
|---|
| HTML # the-history-interface |