History.pushState()

HTML 文書では、history.pushState() メソッドはブラウザーのセッション履歴スタックに状態を追加します。

history.pushState(state, title[, url])

state

state (状態)オブジェクトは、pushState() によって作られる新規履歴エントリに関連した JavaScript オブジェクトです。ユーザーが新規の state にナビゲートしたときはいつも、popstate イベントが発火し、イベントの state プロパティは、履歴エントリの state オブジェクトのコピーを含みます。

state オブジェクトはシリアライズ可能なあらゆものとなりえます。Firefox では状態オブジェクトをユーザーのディスクに保存してブラウザーを再起動した後にも復帰できるため、state オブジェクトのシリアライズ表現を最大 640k 文字という上限を課しています。これを超える大きさの状態オブジェクトを pushState() に渡した場合、このメソッドは例外を投げます。これ以上のスペースが必要な場合、sessionStorage や localStorageの使用が推奨されます。

title

たいていのブラウザーはこのパラメーターを無視しますが、将来使うかもしれません。ここに空文字を渡すと、将来メソッドが変更されても安全でしょう。あるいは、これから移動する状態の短いタイトルを渡すこともできます。タイトルが変わりうる場合は、document.title を使用できます。

url 省略可

履歴エントリーの URL は、このパラメーターで与えられます。ブラウザーは pushState() を呼び出した後もこの URL を読み込もうとせずに、例えばユーザーがブラウザーを再起動した後など、後で URL を読み込む場合もあるのにご注意ください。新 URL は絶対パスとは限りません。つまり相対パスの場合、現在の URL から相対的に解決されます。新URL は現在の URL と同一 オリジン でなければならず、そうでない場合、pushState() は例外をスローします。このパラメーターが指定されない場合、ドキュメントの現在の URL がセットされます。

ある意味で、pushState() の呼び出しは window.location = "#foo"と似ていて、両方とも現在の文書に関連した別の履歴エントリを作成、アクティベートします。しかし pushState() にはいくつかの利点があります:

• 新しい URL は現在の URL と同一オリジンのいかなる URL にできます。これに対して、window.location をセットするのは、ハッシュを変更した時のみ同一ドキュメントのままになります。
• URL を変えたくないときは変更しなくても良いです。これに対して、g window.location = "#foo"; をセットするのは現在のハッシュが #foo でない場合のみ新規の履歴エントリを作成します。
• 履歴エントリに任意のデータを関連づけることができます。ハッシュベースのアプローチでは、関連するデータすべてを短い文字列にエンコードする必要があります。

pushState() は hashchange イベントを発火せず、それは新URL がハッシュだけ旧URL と異なる場合でもそうなることに気をつけてください。

これはブラウザー履歴エントリに state, title, url をセットしたものを作成します。

const state = { 'page_id': 1, 'user_id': 5 }
const title = ''
const url = 'hello-world.html'

history.pushState(state, title, url)

const url = new URL(window.location);
url.searchParams.set('foo', 'bar');
window.history.pushState({}, '', url);

• Working with the History API
• Window: popstate event