History: pushState() 方法

語法

pushState(state, unused)
pushState(state, unused, url)

引數

state

state 物件是一個 JavaScript 物件，它與 pushState() 建立的新歷史條目相關聯。每當使用者導航到新的 state 時，就會觸發一個 popstate 事件，並且事件的 state 屬性包含歷史條目 state 物件的一個副本。

state 物件可以是任何可序列化的內容。

注意： 某些瀏覽器會將 state 物件儲存到使用者的磁碟上，以便在使用者重啟瀏覽器後進行恢復，並且會對 state 物件的序列化表示施加大小限制，如果您傳遞的 state 物件的序列化表示大於該大小限制，則會丟擲異常。因此，如果您希望確保有比某些瀏覽器可能施加的更多的空間，建議使用 sessionStorage 和/或 localStorage。

unused

此引數是出於歷史原因而存在的，不能省略；傳遞空字串可以防止將來對該方法進行更改。

url 可選

新歷史條目的 URL。請注意，瀏覽器在呼叫 pushState() 後不會嘗試載入此 URL，但之後可能會嘗試載入該 URL，例如，在使用者重啟瀏覽器後。新 URL 不需要是絕對路徑；如果是相對路徑，則會相對於當前 URL 進行解析。新 URL 必須與當前 URL 具有相同的 源；否則，pushState() 將丟擲異常。如果未指定此引數，則將其設定為文件的當前 URL。

返回值

無（undefined）。

異常

SecurityError DOMException

如果關聯的文件不是完全活動的，或者提供的 url 引數不是有效的 URL，或者該方法被呼叫的頻率過高，則會丟擲此異常。

DataCloneError DOMException

如果提供的 state 引數不可序列化，則會丟擲此異常。

描述

某種程度上，呼叫 pushState() 類似於設定 window.location = "#foo"，因為兩者都會建立並激活與當前文件關聯的另一個歷史條目。但是 pushState() 有一些優點：

• 新的 URL 可以是與當前 URL 同源的任何 URL。相比之下，設定 window.location 只有在僅修改雜湊時才將您保留在同一文件中。
• 更改頁面的 URL 是可選的。相比之下，設定 window.location = "#foo"; 僅噹噹前雜湊不是 #foo 時才會建立新的歷史條目。
• 您可以將任意資料與新的歷史條目關聯。使用基於雜湊的方法，您需要將所有相關資料編碼成一個短字串。

請注意，pushState() 永遠不會觸發 hashchange 事件，即使新 URL 與舊 URL 僅在雜湊部分不同。

示例

這會建立一個新的瀏覽器歷史條目，設定 state 和 url。

JavaScript

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

history.pushState(state, "", url);

更改查詢引數

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

規範

瀏覽器相容性

另見

• 使用 History API
• Window: popstate 事件