jQuery URL 參數操作插件：$.query 獲取、設置、刪除查詢字串完整指南

在前端開發中，頻繁需要解析、構建、修改 URL 查詢字串。jquery.query.js 是一款輕量、功能強大的插件，提供鏈式 API 操作 URL 參數，支援多值參數、陣列存取、參數增刪改查等場景。本文詳細介紹其核心用法與實戰技巧。

引入插件

<script src="https://cdn.jsdelivr.net/npm/jquery-query@2.1.7/jquery.query.min.js"></script>

<script src="js/jquery.query.js"></script>

核心 API 快速參考

實戰範例詳解

1. 獲取參數

// 假設當前 URL: https://example.com/page?test=1&kk=2&tag=js&tag=jquery&tag=plugin

// 單值參數
var testVal = $.query.get('test');        // "1"
var kkVal = $.query.get('kk');            // "2"

// 多值參數（同名）
var tags = $.query.get('tag');            // ["js", "jquery", "plugin"]
var secondTag = $.query.get('tag[1]');    // "jquery" (索引 1)
var firstTag = $.query.get('tag[0]');     // "js" (索引 0)

// 不存在的參數
var missing = $.query.get('none');        // "" (空字串)

2. 設置/新增參數（鏈式操作）

// 新增單個參數
var newUrl = $.query.set('section', 5).toString();  
// 輸出: "?section=5"

// 連續設置多個參數
var newUrl = $.query.set('section', 5).set('action', 'do').toString();  
// 輸出: "?action=do§ion=5" (參數按字母序排序)

// 基於當前 URL 修改
var currentQuery = $.query; // 解析當前 window.location.search
var modified = currentQuery.set('page', 3).set('sort', 'desc').toString();
// 輸出: "?page=3&sort=desc&test=1&kk=2&tag=js&tag=jquery&tag=plugin" (保留原參數)

3. 刪除參數

// 刪除單個參數
var withoutTest = $.query.REMOVE('test').toString();
// 輸出: "?kk=2&tag=js&tag=jquery&tag=plugin"

// 刪除多值參數中的某一項？插件不直接支援，需手動處理：
var tags = $.query.get('tag'); // 獲取陣列
tags.splice(1, 1); // 移除第 2 個
var newQuery = $.query.REMOVE('tag'); // 先刪除所有 tag
tags.forEach(function(t) { newQuery = newQuery.set('tag', t); }); // 重新加入
var finalUrl = newQuery.toString();

4. 清空與複製

// 清空所有參數，僅保留路徑
var cleanUrl = $.query.empty().toString(); // ""

// 複製當前查詢對象進行獨立操作
var copyQuery = $.query.copy();
copyQuery.set('debug', 'true');
console.log(copyQuery.toString()); // 含 debug
console.log($.query.toString());   // 原查詢不變

5. 解析任意 URL 字串（非當前頁面）

var url = "https://api.example.com/search?q=javascript&page=2&filter=recent&filter=popular";
var parsed = $.query.load(url); // 靜態方法解析指定 URL

var q = parsed.get('q');           // "javascript"
var page = parsed.get('page');     // "2"
var filters = parsed.get('filter'); // ["recent", "popular"]

// 修改後輸出新 URL
var newUrl = parsed.set('page', 3).REMOVE('filter').set('filter', 'all').toString();
// "https://api.example.com/search?q=javascript&page=3&filter=all"

進階技巧與注意事項

• 編碼處理：插件內部自動處理 encodeURIComponent/decodeURIComponent，中文參數無需手動編解碼。
• 參數排序：toString() 輸出的參數按鍵名字母序排序，便於快取比較、簽名驗證。
• 無 jQuery 環境：插件依賴 jQuery，若專案使用原生 JS，可考慮 URLSearchParams (現代瀏覽器原生支援) 或 query-string (npm 套件)。
• 陣列參數命名：後端框架對陣列參數解析規則不同（PHP 需 name[]，Java/Node 直接支援同名），插件只負責前端字串操作，需配合後端約定。

原生替代方案：URLSearchParams (ES2015+)

// 現代瀏覽器無需引入插件
const params = new URLSearchParams(window.location.search);

// 獲取
params.get('test');           // "1" (首個值)
params.getAll('tag');         // ["js", "jquery", "plugin"] (所有值)

// 設置/新增
params.set('page', '3');      // 替換所有 page
params.append('tag', 'vue');  // 新增同名參數

// 刪除
params.delete('test');        // 刪除所有 test
// 刪除陣列中特定值需手動：getAll → filter → delete → append 迴圈

// 輸出
params.toString();            // "kk=2&tag=js&tag=jquery&tag=plugin&page=3&tag=vue"

$.query 插件雖然歷史悠久，但在需要支援舊版瀏覽器、追求鏈式 API 優雅語法、或處理複雜多值參數場景時，依然是極佳選擇。現代專案可視瀏覽器兼容性要求，選擇原生 URLSearchParams 或繼續使用此插件。