History: replaceState() メソッド

Baseline 広く利用可能

この機能は広く実装されており、多くのバージョンの端末やブラウザーで動作します。2015年7月以降、すべてのブラウザーで利用可能です。

History.replaceState() メソッドは、現在の履歴を編集し、メソッドに引数で渡された状態オブジェクトや URL で置き換えます。このメソッドは、ユーザーのアクションに応じて現在の履歴項目の状態オブジェクトや URL を更新したい場合に特に便利です。

このメソッドは非同期です。移動が完了したときを検知したい場合は popstate イベントのリスナーを追加してください。

構文

replaceState(state, unused)
replaceState(state, unused, url)

引数

state: オブジェクトで、 replaceState メソッドに渡された履歴項目に関連付けられます。状態オブジェクトは null を指定することができます。
unused: この引数は歴史的な理由のために存在しており、省略することはできません。空文字を渡すことが、将来このメソッドに変更が加えられたときに安全です。
url 省略可: 履歴項目の URL です。新しい URL は現在の URL と同じオリジンでなければなりません。もしそうでないと、 replaceState で例外が発生します。

例

https://www.mozilla.org/foo.html が以下の JavaScript を実行したとします。

const stateObj = { foo: "bar" };
history.pushState(stateObj, "", "bar.html");

次のページでは、 history.state を使用して、追加したばかりの stateObj にアクセスすることができます。

上記の 2 行の説明は、履歴 API での作業の記事の pushState() の例にあります。次に、 https://www.mozilla.org/bar.html が以下の JavaScript を実行したとします。

history.replaceState(stateObj, "", "bar2.html");

これにより、URL バーに https://www.mozilla.org/bar2.html が表示されるようになりますが、ブラウザーが bar2.html を読み込んだり、bar2.html が存在するかどうかを確認したりすることはありません。

ユーザーが https://www.microsoft.com に移動し、戻るボタンをクリックしたとします。この時点で、URL バーには https://www.mozilla.org/bar2.html が表示されます。ユーザーがもう一度「戻る」ボタンをクリックすると、URL バーには https://www.mozilla.org/foo.html が表示され、 bar.html は完全にバイパスされます。