History.pushState()

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

構文

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

パラメーター

state
状態オブジェクトは、pushState()によって作られる新規履歴エントリに関連したJavaScript オブジェクトです。 ユーザーが新規の状態にナビゲートしたときはいつも、popstate イベントが発火し、イベントの state プロパティは、履歴エントリの状態オブジェクトのコピーを含みます。
状態オブジェクトはシリアライズ可能なあらゆものとなりえます。Firefox では状態オブジェクトをユーザーのディスクに保存してブラウザーを再起動した後にも復帰できるため、状態オブジェクトのシリアライズ表現を最大 640k 文字という上限を課しています。これを超える大きさの状態オブジェクトをpushState()に渡した場合、このメソッドは例外を投げます。これ以上のスペースが必要な場合、sessionStoragelocalStorageの使用が推奨されます。
title
たいていのブラウザーはこのパラメーターを無視しますが、将来使うかもしれません。ここに空文字を渡すと、将来メソッドが変更されても安全でしょう。あるいは、これから移動する状態の短いタイトルを渡すこともできます。
url Optional
The new history entry's URL is given by this parameter. Note that the browser won't attempt to load this URL after a call to pushState(), but it might attempt to load the URL later, for instance after the user restarts the browser. The new URL does not need to be absolute; if it's relative, it's resolved relative to the current URL. The new URL must be of the same origin as the current URL; otherwise, pushState() will throw an exception. If this parameter isn't specified, it's set to the document's current URL.

説明

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

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

Note that pushState() never causes a hashchange event to be fired, even if the new URL differs from the old URL only in its hash.

This creates a new browser history state setting the state, title, and url.

JavaScript

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

history.pushState(state, title, url)

仕様

仕様書 策定状況 コメント
HTML Living Standard
History.pushState() の定義
現行の標準 No change from HTML5.
HTML5
History.pushState() の定義
勧告 初期定義

ブラウザー実装状況

Update compatibility data on GitHub
デスクトップモバイル
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewAndroid 版 ChromeAndroid 版 FirefoxAndroid 版 OperaiOSのSafariSamsung Internet
pushStateChrome 完全対応 5Edge 完全対応 12Firefox 完全対応 4
補足
完全対応 4
補足
補足 Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
IE 完全対応 10Opera 完全対応 11.5Safari 完全対応 5WebView Android 完全対応 ≤37Chrome Android 完全対応 18Firefox Android 完全対応 4
補足
完全対応 4
補足
補足 Until Firefox 5, the passed object is serialized using JSON. Starting in Firefox 6, the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.
Opera Android 完全対応 11.5Safari iOS 完全対応 4.3Samsung Internet Android 完全対応 1.0
Whether the title argument is usedChrome 未対応 なしEdge 未対応 なしFirefox 未対応 なしIE 未対応 なしOpera 未対応 なしSafari 完全対応 ありWebView Android 未対応 なしChrome Android 未対応 なしFirefox Android 未対応 なしOpera Android 未対応 なしSafari iOS ? Samsung Internet Android 未対応 なし

凡例

完全対応  
完全対応
未対応  
未対応
実装状況不明  
実装状況不明
実装ノートを参照してください。
実装ノートを参照してください。

関連情報