History.pushState()

由於本文件沒有此語言的翻譯版本,您閱讀的是英文版的內容。 幫助我們翻譯這篇文章!

In an HTML document, the history.pushState() method adds a state to the browser's session history stack.

Syntax

history.pushState(state, title, url);

Parameters

state
The state object is a JavaScript object which is associated with the new history entry created by pushState(). Whenever the user navigates to the new state, a popstate event is fired, and the state property of the event contains a copy of the history entry's state object.
The state object can be anything that can be serialized. Because Firefox saves state objects to the user's disk so they can be restored after the user restarts the browser, we impose a size limit of 640k characters on the serialized representation of a state object. If you pass a state object whose serialized representation is larger than this to pushState(), the method will throw an exception. If you need more space than this, you're encouraged to use sessionStorage and/or localStorage.
title
Most browsers currently ignores this parameter, although they may use it in the future. Passing the empty string here should be safe against future changes to the method. Alternatively, you could pass a short title for the state to which you're moving.
url
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. This parameter is optional; if it isn't specified, it's set to the document's current URL.

Note: In Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) through Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), the passed object is serialized using JSON. Starting in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3), the object is serialized using the structured clone algorithm. This allows a wider variety of objects to be safely passed.

In a sense, calling pushState() is similar to setting window.location = "#foo", in that both will also create and activate another history entry associated with the current document. But pushState() has a few advantages:

  • The new URL can be any URL in the same origin as the current URL. In contrast, setting window.location keeps you at the same document only if you modify only the hash.
  • You don't have to change the URL if you don't want to. In contrast, setting window.location = "#foo"; only creates a new history entry if the current hash isn't #foo.
  • You can associate arbitrary data with your new history entry. With the hash-based approach, you need to encode all of the relevant data into a short string.

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.

In other documents, it creates an element with a null namespace URI.

Examples

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

JavaScript

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

history.pushState(state, title, url)

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'History.pushState()' in that specification.
Living Standard No change from HTML5.
HTML5
The definition of 'History.pushState()' in that specification.
Recommendation Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
pushStateChrome Full support 5Edge Full support 12Firefox Full support 4
Notes
Full support 4
Notes
Notes In Firefox 2 through 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 Full support 10Opera Full support 11.5Safari Full support 5WebView Android Full support YesChrome Android Full support YesFirefox Android Full support YesOpera Android Full support YesSafari iOS Full support 4.3Samsung Internet Android ?
Whether the title argument is usedChrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari Full support YesWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS ? Samsung Internet Android ?

Legend

Full support  
Full support
No support  
No support
Compatibility unknown  
Compatibility unknown
See implementation notes.
See implementation notes.

See also