萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

jQuery serialize() 完整指南:表單序列化核心原理、AJAX 實戰與 param/serializeArray 底層解析

前言

serialize() 是 jQuery 將表單資料轉為 URL 編碼字串的核心方法,廣泛用於 AJAX 提交。本文將系統講解其定義、語法、關鍵限制(name 屬性、成功控制項)、實戰模式,並深入剖析底層 $.param() 與 serializeArray() 的實現原理,助你徹底掌握表單序列化全鏈路。

一、serialize() 定義、語法與核心規則

語法

$(selector).serialize()

selector 可為 <form>、單一或多個表單控制項(input、textarea、select)。

四大核心規則(必須遵守)

  1. 只序列化「成功的控制項」:未勾選的 checkbox/radio、disabled 元素、無 name 屬性的元素、提交按鈕(非點擊提交時)會被忽略。
  2. 必須有 name 屬性:<input name="username"> 才會被序列化,id 無效。
  3. 避免使用 JS 保留字作為 name:如 length、constructor 等會導致取值異常。
  4. 檔案輸入不支援:<input type="file"> 不會被序列化(需用 FormData)。

反面教材

<form id="form1">
    <input name="length" value="pipi"> <!-- 錯誤:length 為保留字 -->
    <input name="blog" value="blue">
</form>
$('#form1').serialize(); // 無法正常獲取 length 值

二、實戰應用模式

1. AJAX 提交標準模式

$.ajax({
    type: 'POST',
    dataType: 'json',
    url: '/api/submit',
    data: $('#myForm').serialize(), // 直接序列化整個表單
    success: function(res) { console.log(res); }
});

2. 手動觸發序列化預覽

<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
});

3. 區域序列化:僅提交特定區塊

// 僅序列化某個區塊內的輸入框
var partialData = $('#step1 :input').serialize();
// 或排除某些欄位
var filtered = $('#form :input').not('[name="token"]').serialize();

三、底層原理:$.param() 與 serializeArray() 源碼解析

1. serializeArray():表單 → 陣列物件

將表單元素轉為標準結構陣列:

[
    { 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();
}

2. $.param():陣列/物件 → URL 編碼字串

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 標準
}

3. 直接使用 $.param() 的場景

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 屬性是序列化的身分證,成功控制項是入場券。

copyright © 萬盛學電腦網 all rights reserved