History: replaceState() メソッド

Baseline Widely available

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

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

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

構文

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

引数

state

オブジェクトで、 replaceState メソッドに渡された履歴項目に関連付けられます。状態オブジェクトは null を指定することができます。

unused

この引数は歴史的な理由のために存在しており、省略することはできません。空文字を渡すことが、将来このメソッドに変更が加えられたときに安全です。

url 省略可

履歴項目の URL です。新しい URL は現在の URL と同じオリジンでなければなりません。もしそうでないと、 replaceState で例外が発生します。

返値

なし (undefined)。

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

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

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

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

js
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 は完全にバイパスされます。

仕様書

Specification
HTML
# dom-history-replacestate-dev

ブラウザーの互換性

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
replaceState
Whether the unused parameter is used
DeprecatedNon-standard

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
No support
No support
Non-standard. Check cross-browser support before using.
Deprecated. Not for use in new websites.
See implementation notes.