單頁應用(SPA)或傳統多頁網站常需根據 URL 參數(如 ?type=1&id=100)決定初始狀態、篩選條件或分頁。原生 window.location.search 只能取得原始字串,需自行解析。本文提供一個輕量、可複用的 QueryString 工具類,並示範搭配下拉選單同步 URL 狀態。
class QueryString {
constructor() {
this.data = {};
this.parse();
}
/** 解析當前頁面 URL 參數 */
parse() {
const search = window.location.search.slice(1); // 移除開頭 '?'
if (!search) return;
search.split('&').forEach(pair => {
const [key, ...valParts] = pair.split('=');
if (key) {
// 解碼並支援多個同名參數(取最後一個)
this.data[decodeURIComponent(key)] = decodeURIComponent(valParts.join('='));
}
});
}
/** 取得參數值,不存在回傳 undefined */
get(key) {
return this.data[key];
}
/** 取得所有參數物件副本 */
getAll() {
return { ...this.data };
}
/** 產生新的查詢字串(可選擇性合併/覆蓋參數) */
stringify(extra = {}) {
const merged = { ...this.data, ...extra };
return '?' + Object.entries(merged)
.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
.join('&');
}
/** 導航至新參數(不重新整理頁面時配合 History API) */
navigate(extra = {}, { replace = false } = {}) {
const url = `${location.pathname}${this.stringify(extra)}${location.hash}`;
if (replace) history.replaceState(null, '', url);
else history.pushState(null, '', url);
this.parse(); // 同步內部狀態
}
}
// 掛載單例供全域使用
window.QS = new QueryString();
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8">
<title>QueryString Demo</title>
<style>
body { font-family: sans-serif; padding: 2rem; max-width: 600px; margin: 0 auto; }
select { padding: 0.5rem; font-size: 1rem; }
.current { margin-top: 1rem; color: #666; font-size: 0.9rem; }
</style>
</head>
<body>
<h2>產品類型篩選</h2>
<select id="typeSelect">
<option value="">全部</option>
<option value="1">企業</option>
<option value="2">產品</option>
<option value="3">新聞</option>
</select>
<div class="current">當前 URL 參數:</div>
<script>
// 引用上方 QueryString 類別
const qs = window.QS;
const select = document.getElementById('typeSelect');
const display = document.getElementById('paramDisplay');
// 初始化:根據 URL 設定下拉選單
const initType = qs.get('type');
if (initType) select.value = initType;
updateDisplay();
// 使用者切換時更新 URL(使用 replaceState 避免歷史堆疊)
select.addEventListener('change', () => {
qs.navigate({ type: select.value || undefined }, { replace: true });
updateDisplay();
// 這裡可觸發資料重新載入:loadData(select.value);
});
function updateDisplay() {
display.textContent = JSON.stringify(qs.getAll());
}
</script>
</body>
</html>
// 使用者點擊分頁
qs.navigate({ page: 2 }, { replace: true });
// 重置篩選但保留排序
qs.navigate({ category: undefined, keyword: undefined }, { replace: true });
?tag=js&tag=vue)// 擴充 parse() 支援陣列
parse() {
// ...
if (this.data[key]) {
// 已存在則轉為陣列
this.data[key] = Array.isArray(this.data[key])
? [...this.data[key], val]
: [this.data[key], val];
} else {
this.data[key] = val;
}
}
static parseUrl(url) {
const qs = new QueryString();
qs.data = {};
const search = new URL(url).search.slice(1);
// ... 同 parse 邏輯
return qs;
}
URLSearchParams vs 自製工具| 特性 | URLSearchParams (原生) | 自製 QueryString |
|---|---|---|
| 瀏覽器支援 | IE 不支援(需 Polyfill) | 全瀏覽器(含 IE9+) |
| 多值參數 | .getAll() 原生支援 | 需自行擴充 |
| 同步 History | 需自行寫入 | 內建 navigate() |
| 解碼處理 | 自動 | 自動 |
| 體積 | 0(內建) | <1KB (gzipped) |
建議: 現代專案(不需支援 IE)優先使用原生
URLSearchParams;需支援舊瀏覽器或想要內建導航同步功能時,採用本文工具類或 lodash / query-string 等成熟庫。