履歴 API

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since 2015年7月.

履歴 API は、ブラウザーのセッション履歴 (WebExtensions history と混同しないように) へのアクセスをグローバルの history オブジェクトを介して提供しています。このオブジェクトは、ユーザーの履歴の中を前のページや後のページへ移動したり、履歴スタックの中を操作したりするのに便利なメソッドやプロパティが提供されています。

メモ: この API が利用可能なのはメインスレッド (Window) のみです。 Worker や Worklet コンテキストではアクセスできません。

概念と使用方法

ユーザーの履歴の中を前のページや次のページへ移動するには、 back(), forward(), go() の各メソッドを使用します。

前のページや次のページへの移動

履歴を前に遡るには、次のようにします。

history.back();

これは、ちょうどユーザーがブラウザーのツールバーの戻るボタンをクリックしたときのような動作です。

同様に、次のようにして (ユーザーが次へボタンをクリックしたときのように) 次のページへ進むこともできます。

history.forward();

履歴内の特定の位置まで移動

go() メソッドを使うと、セッション履歴において現在のページから相対的な位置を指定して特定のページを読み込むことができます。 (現在のページの相対位置は 0 となります。)

ひとつ前のページへと戻る例です (back() と同様の動き)。

history.go(-1);

ページを進める例で、 forward() を呼び出すのと同様です。

history.go(1);

同様に、 2 を渡すことで 2 ページ分を進めることができます。

go() メソッドの他の使い方として、 0 を渡すか、引数なしで呼び出すことで、現在のページを再読み込みすることができます。

js
// 以下の文は、
// どちらもページを再読み込みする
// 効果があります。
history.go(0);
history.go();

length プロパティの値を参照することにより、履歴スタック中のページの数を知ることができます。

const numberOfEntries = history.length;

インターフェイス

History

ブラウザーのセッション履歴（すなわち、現在のページが読み込まれているタブやフレームで表示したことがあるページ群）の操作ができます。

PopStateEvent

popstate イベントのインターフェイスです。

例

以下の例では popstate イベントのリスナーを割り当てています。 history オブジェクトのメソッドで現在のタブのブラウザー履歴の追加、置換、移動など、いくつかの操作を説明しています。

js
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}"