單頁應用(SPA)響應快、體驗順,但有個惱人的缺陷:點了半天菜單,網址列完全沒變,按瀏覽器「上一頁」還會直接跳出你的網站。HTML5 的 History API 就是為了解決這件事而生。本文從 API 講到完整可跑的範例。
為了提升反應速度,越來越多開發者採用單頁結構:頁面之間切換時不刷新整個文件,只用 AJAX 更新局部內容。你如果使用 Chrome 或 Firefox 逛過 GitHub、Google+ 這類網站,會發現點擊連結時內容瞬間換掉,同時網址列也變了,而且瀏覽器的前進後退完全正常。
做到這件事的,就是 HTML5 新增的兩個方法:history.pushState() 與 history.replaceState()。
interface History {
readonly attribute long length; // 歷史堆疊長度
readonly attribute any state; // 目前條目的狀態物件
void go(optional long delta); // 相對跳轉
void back(); // 等於上一頁
void forward(); // 等於下一頁
void pushState(any data, DOMString title, optional DOMString? url = null);
void replaceState(any data, DOMString title, optional DOMString? url = null);
};

這是最該記清楚的一點:
pushState() 會新增一筆歷史記錄。使用者按「上一頁」能回到前一個狀態。replaceState() 取代目前這筆歷史記錄,不新增。效果類似 location.replace()。什麼時候用 replaceState?當你只是想「更新目前條目的狀態或網址」,不該讓使用者按上一頁回到舊版本時——例如把使用者剛填的表單草稿寫進 state,或把 ?page=1 這種預設參數補進網址,用 replaceState 就很合適。
左側是城市選單,點下去右側用 AJAX 載入該城市的資料,同時網址的 hash 改變,前進後退都能正確還原內容。

監看網路面板可以發現:同一個網址再次拜訪不會重複請求,因為有做過判斷。

<body>
<center><strong>bbSPA 測試頁面</strong></center>
<hr>
<ul id="list" style="float:left; list-style:none;">
<li><a href="#beijing">北京</a></li>
<li><a href="#shanghai">上海</a></li>
<li><a href="#shenzhen">深圳</a></li>
<li><a href="#guangzhou">廣州</a></li>
<li><a href="#tianjin">天津</a></li>
</ul>
<div id="content-main"
style="margin-left:50px; float:left; width:220px;
border:1px solid #ccc; height:120px; color:#ff3300;"></div>
</body>
$(function () { _init(); });
var _history = []; // 記錄 hash 的活動資料容器
function _init() {
var root = $("#list");
var defaultHash = root.find("li a").eq(1).attr("href"); // 預設上海
var currentHash = window.location.hash;
_addToHistory(defaultHash, true); // 用 replaceState 寫入初始狀態
if (currentHash && currentHash != defaultHash) {
_showContent(currentHash.split("#")[1]);
} else {
_showContent(defaultHash.split("#")[1]);
}
$("#list").on("click", "a", function (e) {
_showContent($(this).attr("href").split("#")[1]);
e.preventDefault(); // 阻擋原生跳轉,改走 AJAX
});
// 使用者按上一頁 / 下一頁時觸發
window.addEventListener("popstate", function (e) {
if (e.state && e.state.hash) {
var hash = e.state.hash;
if (_history[1] && hash === _history[1].hash) {
_showContent(hash.split("#")[1].toLowerCase());
} else {
return; // 其他視為非法前進 / 後退
}
} else {
return;
}
}, false);
}
function _showContent(action) {
var samePage = _history[0]["hash"] == "#" + action;
if (samePage) { return; } // 同頁面不重複載入
_loadContent(action + ".data")
.done(function (data) {
_renderContent(data["content"]);
_addToHistory("#" + action, samePage);
})
.fail(function () { throw new Error("load content error !"); });
}
function _loadContent(url) {
return $.AJax({ url: url, dataType: "JSon" });
}
function _renderContent(text) { $("#content-main").text(text); }
function _addToHistory(hash, noState) {
var obj = { hash: hash };
if (noState) {
_history.shift(obj);
window.history.replaceState(obj, "", hash);
} else {
window.history.pushState(obj, "", hash);
}
_history.unshift(obj);
}
https://localhost:8888/bbSPA.Html,但透過 replaceState 立刻變成 ...bbSPA.Html#shanghai,並同步載入 shanghai.data。用 replaceState 而非 pushState,是因為這不該佔用一筆「上一頁」。pushState 把網址改成對應 hash。window.onpopstate。這個範例必須透過 HTTP 伺服器開啟,用 https://host/ 的形式訪問才會生效。若直接用 file:// 在瀏覽器打開,會看到:
Uncaught SecurityError: A history state object with URL 'file:///C:/xxx/xxx/xxx/xxx.Html' cannot be created in a document with origin 'null'.
原因是 pushState 的網址必須與目前頁面同源,而 file:// 打開的頁面 origin 是 null,因此被拒絕。解法很簡單:在本機跑一個簡易伺服器(例如 python -m http.server)再訪問即可。
只支援 hash 並不是完整的 SPA 路由。這個範例刻意用了 hash(#beijing),因為 hash 變化不會請求伺服器,靜態伺服器就能跑。若要做出 /city/beijing 這種乾淨網址,伺服器端必須把未知路徑都回傳同一份 index.html,讓前端路由接管。
第二個參數 title 目前是被忽略的。規格中原本要拿來設定頁面標題,但瀏覽器實作並未採用,請傳空字串就好,標題還是用 document.title 設定。
第三個參數的長度限制。部分瀏覽器對網址長度有上限,請勿把大量資料塞進網址;狀態資料應放在第一個參數的物件裡。
別忘了 popstate 與 hashchange 是兩件事。pushState 不會觸發 hashchange,而使用者手動改 hash 只會觸發 hashchange 不觸發 popstate。混用兩種路由風格時要特別小心。
以上就是本次筆記的全部內容。History API 的觀念其實不複雜,真正需要仔細想清楚的是「哪些狀態該佔一筆歷史記錄」——這會直接決定使用者按上一頁時的體驗是否合理。