serialize() 是 jQuery 將表單資料轉為 URL 編碼字串的核心方法,廣泛用於 AJAX 提交。本文將系統講解其定義、語法、關鍵限制(name 屬性、成功控制項)、實戰模式,並深入剖析底層 $.param() 與 serializeArray() 的實現原理,助你徹底掌握表單序列化全鏈路。
$(selector).serialize()
selector 可為 <form>、單一或多個表單控制項(input、textarea、select)。
name 屬性的元素、提交按鈕(非點擊提交時)會被忽略。name 屬性:<input name="username"> 才會被序列化,id 無效。length、constructor 等會導致取值異常。<input type="file"> 不會被序列化(需用 FormData)。<form id="form1">
<input name="length" value="pipi"> <!-- 錯誤:length 為保留字 -->
<input name="blog" value="blue">
</form>
$('#form1').serialize(); // 無法正常獲取 length 值
$.ajax({
type: 'POST',
dataType: 'json',
url: '/api/submit',
data: $('#myForm').serialize(), // 直接序列化整個表單
success: function(res) { console.log(res); }
});
<form id="myForm">
暱稱 <input type="text" name="username" value="admin"><br>
密碼 <input type="password" name="password" value="admin123"><br>
<button type="button" id="submit">序列化表單</button>
</form>
$('#submit').click(function() {
alert($('#myForm').serialize());
// 輸出:username=admin&password=admin123
});
// 僅序列化某個區塊內的輸入框
var partialData = $('#step1 :input').serialize();
// 或排除某些欄位
var filtered = $('#form :input').not('[name="token"]').serialize();
將表單元素轉為標準結構陣列:
[
{ name: 'username', value: 'admin' },
{ name: 'password', value: 'admin123' }
]
核心邏輯(精簡):
serializeArray: function() {
return this.map(function() {
return this.elements ? jQuery.makeArray(this.elements) : this;
})
.filter(function() {
// 過濾:有 name、未 disabled、且為成功控制項
return this.name && !this.disabled &&
(this.checked || /select|textarea/i.test(this.nodeName) ||
/text|hidden|password|search/i.test(this.type));
})
.map(function(i, elem) {
var val = $(this).val();
return val == null ? null :
$.isArray(val) ? $.map(val, function(v) { return {name: elem.name, value: v}; }) :
{name: elem.name, value: val};
}).get();
}
serialize() 內部實際上是 $.param( $(form).serializeArray() ) 的簡易封裝。
param: function(a) {
var s = [];
function add(key, value) {
s.push(encodeURIComponent(key) + '=' + encodeURIComponent(value));
}
// 陣列或 jQuery 物件:遍歷元素
if ($.isArray(a) || a.jquery) {
$.each(a, function() { add(this.name, this.value); });
}
// 純物件:遍歷鍵值
else {
for (var j in a) {
var val = a[j];
if ($.isArray(val)) $.each(val, function() { add(j, this); });
else add(j, $.isFunction(val) ? val() : val);
}
}
return s.join('&').replace(/%20/g, '+'); // 空格轉 + 符合 application/x-www-form-urlencoded 標準
}
var obj = { a: 1, b: 2, c: [3, 4] };
$.param(obj); // "a=1&b=2&c=3&c=4"
// 配合 AJAX 發送 JSON 物件(非表單)
$.ajax({
url: '/api',
data: $.param({ id: 1, tags: ['js', 'jquery'] }), // 自動展開陣列
contentType: 'application/x-www-form-urlencoded'
});
| 場景 | 解決方案 |
|---|---|
多選 select multiple 或 checkbox 群組 | 同名 name="tags[]",$.param 會自動展開為 tags[]=a&tags[]=b(PHP 等後端自動識別為陣列) |
| 需發送 JSON 格式而非表單編碼 | 使用 JSON.stringify(data) + contentType: 'application/json',勿用 serialize() |
| 動態新增的表單元素 | 確保新增元素有 name,serialize() 會自動包含 |
| 檔案上傳 | 改用 FormData:new FormData(form[0]) |
| 巢狀物件序列化 | serialize() 不支援巢狀,需手動展平或用 $.param(巢狀物件) |
$(form).serialize()
│
▼
$(form).serializeArray() → [ {name, value}, ... ] (陣列物件)
│
▼
$.param( array ) → "name=value&name=value" (URL 編碼字串)
│
▼
$.ajax({ data: ... }) → 發送請求
serialize() 看似簡單,實則串聯了 表單控制項篩選 → 陣列物件結構化 → URL 編碼 三大核心步驟。理解 serializeArray() 與 $.param() 的獨立價值,能讓你在非表單場景(如組裝複雜查詢參數、快取鍵生成)中同樣得心應手。記住鐵律:name 屬性是序列化的身分證,成功控制項是入場券。