解析 URL 查詢字符串是前端路由、分頁、篩選、追蹤參數的基礎。現代瀏覽器原生 URLSearchParams 提供標準、高效、可迭代的 API,取代手工 split/regex 解析。本文詳解用法、兼容封裝、數組參數處理、TypeScript 類型定義。
// 當前頁面 URL
const params = new URLSearchParams(window.location.search);
// 獲取單值(首個)
params.get('id'); // '123' 或 null
// 獲取所有同名值(數組)
params.getAll('tag'); // ['js', 'ts', 'vue']
// 判斷存在
params.has('keyword'); // boolean
// 迭代
for (const [key, value] of params) { ... }
params.forEach((value, key) => { ... });
// 修改
params.set('page', '2'); // 替換所有同名
params.append('tag', 'react'); // 新增
params.delete('tag'); // 刪除所有同名
params.sort(); // 按鍵排序(穩定)
// 輸出查詢字符串
params.toString(); // 'id=123&page=2&tag=js&tag=ts'
function parseQuery(search = window.location.search, options = {}) {
const { arrayFormat = 'bracket', parseNumbers = false, parseBooleans = false } = options;
// arrayFormat: 'bracket' (foo[]=1&foo[]=2) | 'comma' (foo=1,2) | 'index' (foo[0]=1)
// 簡易實現:優先用原生,降級手工解析
if (typeof URLSearchParams !== 'undefined' && arrayFormat === 'bracket') {
return new URLSearchParams(search.replace('?', ''));
}
// 手工解析(支援多種格式)...
// 此處省略,生產環境建議使用 query-string 庫
}
// 通用獲取函數
function getQuery(key, { all = false, parse = false } = {}) {
const params = new URLSearchParams(window.location.search);
const val = all ? params.getAll(key) : params.get(key);
if (!parse || val === null) return val;
// 簡單類型推斷
if (val === 'true') return true;
if (val === 'false') return false;
if (/^\d+$/.test(val)) return Number(val);
return val;
}
interface QueryParams {
page?: string;
limit?: string;
tags?: string[];
sort?: 'asc' | 'desc';
}
function parseQuery(): QueryParams {
const params = new URLSearchParams(window.location.search);
return {
page: params.get('page') ?? undefined,
limit: params.get('limit') ?? undefined,
tags: params.getAll('tags'),
sort: (params.get('sort') as QueryParams['sort']) ?? undefined
};
}
// 使用
const { page = '1', limit = '20', tags = [], sort = 'desc' } = parseQuery();
function buildUrl(base, params) {
const usp = new URLSearchParams();
Object.entries(params).forEach(([k, v]) => {
if (Array.isArray(v)) v.forEach(item => usp.append(k, item));
else if (v !== undefined && v !== null) usp.set(k, v);
});
return `${base}?${usp.toString()}`;
}
buildUrl('/api/users', { page: 2, tags: ['js', 'ts'], sort: 'asc' });
// '/api/users?page=2&tags=js&tags=ts&sort=asc'
const hashParams = new URLSearchParams(window.location.hash.split('?')[1] || '');