jquery-query (或 jQuery.query) 是一個輕量級 jQuery 外掛,提供鏈式 API 解析、構建、操作 URL 查詢字串,支援多值參數、陣列索引、參數增刪改查。
<!-- CDN -->
<script src="https://cdn.jsdelivr.net/npm/jquery@3.7.1/dist/jquery.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/jquery-query@2.1.7/jquery.query.min.js"></script>
<!-- 或 NPM -->
npm install jquery-query
import $ from 'jquery';
import 'jquery-query';
| 操作 | 方法 | 示例 | 說明 |
|---|---|---|---|
| 獲取單值 | $.query.get(key) | $.query.get('id') → "123" | 返回字串,不存在返回空字串 |
| 獲取多值 | $.query.get(key) | $.query.get('tag') → ["java","jsp"] | 同名參數自動返回陣列 |
| 獲取指定索引 | $.query.get('key[0]') | $.query.get('tag[1]') | 取陣列特定元素 |
| 設定參數 | $.query.set(key, val) | $.query.set('p', 2) | 返回 Query 物件,可鏈式調用 |
| 移除參數 | $.query.REMOVE(key) | $.query.REMOVE('debug') | 返回新 Query 物件 |
| 清空所有 | $.query.empty() | 返回空 Query | |
| 複製 | $.query.copy() | 深拷貝 | |
| 輸出字串 | .toString() | "?id=123&tag=java" | 含前綴 ? |
| 解析指定 URL | $.query.load(url) | $.query.load('/search?q=js') | 解析任意 URL 字串 |
// 當前 URL: https://example.com/search?q=javascript&tag=jquery&tag=plugin&page=1
var q = $.query; // 自動解析 window.location.search
console.log(q.get('q')); // "javascript"
console.log(q.get('tag')); // ["jquery", "plugin"]
console.log(q.get('tag[0]')); // "jquery"
console.log(q.get('page')); // "1"
console.log(q.get('none')); // "" (不存在返回空字串)
// 從當前 URL 修改頁碼並新增排序
var newUrl = $.query.set('page', 2).set('sort', 'desc').toString();
// "?q=javascript&tag=jquery&tag=plugin&page=2&sort=desc"
// 移除分頁參數 (首頁不顯示 page=1)
var firstPageUrl = $.query.REMOVE('page').toString();
// 完全替換查詢字串
var customUrl = $.query.empty().set('action', 'search').set('kw', 'java').toString();
// "?action=search&kw=java"
$('.filter-link').click(function(e) {
e.preventDefault();
var $this = $(this);
var paramName = $this.data('param'); // 如 "category"
var paramValue = $this.data('value'); // 如 "tech"
// 更新 URL 參數
var newQuery = $.query.set(paramName, paramValue).REMOVE('page').toString();
// 重置頁碼為 1
// 發送 AJAX
loadData(newQuery);
// 更新瀏覽器歷史 (無刷新換 URL)
history.pushState({}, '', location.pathname + newQuery);
// 更新 UI 激活狀態
$this.addClass('active').siblings().removeClass('active');
});
function loadData(queryString) {
$('#list').load('/api/items' + queryString);
}
var formQuery = $('#searchForm').serialize(); // "kw=java&category=backend&page=1"
// 轉為 Query 物件操作
var q = $.query.load('?' + formQuery);
q.set('page', 1); // 重置頁碼
$('#results').load('/search' + q.toString());
var url = 'https://api.example.com/items?category=book&tags=java&tags=spring&page=3';
var q = $.query.load(url);
console.log(q.get('tags')); // ["java", "spring"]
// 取得不含查詢字串的基礎 URL
var baseUrl = location.origin + location.pathname; // "https://example.com/search"
// 組合
var fullUrl = baseUrl + $.query.set('page', 2).toString();
現代專案建議使用原生 URLSearchParams,無依賴、效能更好:
// 解析
const params = new URLSearchParams(window.location.search);
params.get('name'); // 單值
params.getAll('tag'); // 多值陣列 ["a", "b"]
params.has('page'); // 布林
// 修改
params.set('page', '2');
params.append('tag', 'new');
params.delete('debug');
params.sort(); // 排序鍵值
// 輸出
params.toString(); // "name=value&page=2&tag=a&tag=b&tag=new"
// 構建新 URL
const url = new URL(location.href);
url.search = params.toString();
history.pushState({}, '', url);
URLSearchParams:Chrome 49+, Firefox 44+, Safari 10.1+, Edge 17+ (IE 不支援)jquery-query 或 Polyfilljquery-query 提供直觀鏈式 API 操作 URL 參數,適合 jQuery 專案快速開發。現代專案優先使用原生 URLSearchParams,配合 URL 物件操作完整 URL。核心場景:AJAX 分頁篩選聯動、動態構建 API 請求、表單序列化處理、瀏覽器歷史狀態管理。