jQuery `serialize()` 详解

serialize() 是 jQuery 表单序列化方法，把表单内带 name 的表单元素，拼接成 key=value&key2=value2 格式的 URL 编码字符串，专门用于 AJAX 提交表单。

一、基础语法

$(selector).serialize()

• 返回值 ：string 字符串（URL 编码格式）
• 适用对象 ：<form> 标签、表单元素集合（input/select/textarea 等）
• 核心规则 ：只识别带 name 属性 的表单控件，无 name 会直接忽略

---

二、使用前提 & 支持元素

1. 必须满足

1. 元素必须有 name 属性（重中之重）
2. 只处理成功控件 ：
   • 禁用 disabled 的元素 → 忽略
   • 未选中的单选/复选框 → 忽略
   • 隐藏元素 hidden 正常参与序列化

2. 支持的表单标签

input(text/password/radio/checkbox/hidden)、select、textarea

---

三、基础示例

1. 完整表单示例

HTML

<form id="form1">
    <input type="text" name="username" value="张三">
    <input type="password" name="pwd" value="123456">
    <input type="hidden" name="id" value="1001">
    
    <!-- 单选框 -->
    <input type="radio" name="sex" value="1" checked>男
    <input type="radio" name="sex" value="2">女

    <!-- 复选框 -->
    <input type="checkbox" name="hobby" value="game" checked>游戏
    <input type="checkbox" name="hobby" value="music" checked>音乐

    <select name="city">
        <option value="bj" selected>北京</option>
        <option value="sh">上海</option>
    </select>

    <textarea name="remark">备注内容</textarea>
</form>

<button id="btn">序列化</button>

JS

$("#btn").click(function(){
    // 序列化整个表单
    var formData = $("#form1").serialize();
    console.log(formData);
});

输出结果（URL 编码字符串）

username=%E5%BC%A0%E4%B8%89&pwd=123456&id=1001&sex=1&hobby=game&hobby=music&city=bj&remark=%E5%A4%87%E6%B3%A8%E5%86%85%E5%AE%B9

---

四、各类表单控件规则拆解

1. 文本框 / 密码框 / 隐藏域

直接拼接 name=value

<input name="nick" value="小李">

结果：nick=%E5%B0%8F%E6%9D%8E

2. 单选框 radio

只取选中项 ，同 name 只保留一个值

<input type="radio" name="sex" value="1" checked>
<input type="radio" name="sex" value="2">

结果：sex=1

3. 复选框 checkbox

选中项全部保留 ，多个同 name 会生成多组 name=value

<input type="checkbox" name="hobby" value="a" checked>
<input type="checkbox" name="hobby" value="b" checked>

结果：hobby=a&hobby=b

4. 下拉框 select

• 单选 select：取选中 option 的 value
• 多选 select multiple：选中项多组拼接

<select name="area">
  <option value="01" selected>华东</option>
</select>

结果：area=01

5. 禁用元素 disabled

加 disabled 直接忽略，不会进入序列化字符串

<input name="test" value="test" disabled>

→ 无对应参数

---

五、常用场景：搭配 AJAX 提交表单（项目最常用）

标准 AJAX 提交写法

$("#form1").submit(function(e){
    // 阻止表单默认跳转提交
    e.preventDefault();

    // 序列化表单
    var postData = $(this).serialize();

    $.ajax({
        url: "/api/save",
        type: "post",
        data: postData, // 直接传入序列化字符串
        success: function(res){
            console.log("提交成功", res);
        }
    });
});

额外追加参数

如果表单之外还要额外传参，两种写法：

1. 字符串拼接

var data = $("#form1").serialize() + "&type=add&token=123abc";

2. 先转对象再合并（推荐，不易出错） 下文会讲到 serializeArray()

---

六、相关配套方法（对比区分）

1. serializeArray()

和 serialize() 同源，返回 JSON 数组，而非字符串，适合二次加工数据。

示例

var arr = $("#form1").serializeArray();
console.log(arr);

输出格式：

[
  { name: "username", value: "张三" },
  { name: "pwd", value: "123456" },
  { name: "sex", value: "1" }
]

用途

• 遍历修改字段
• 转为 JSON 对象
• 动态增删参数

数组转 JSON 对象工具函数

function serializeToJson(form){
    var res = {};
    $(form).serializeArray().forEach(function(item){
        res[item.name] = item.value;
    });
    return res;
}

// 使用
var json = serializeToJson("#form1");
$.ajax({
    url: "/api/save",
    type: "post",
    data: json // 直接传对象，jQuery 自动拼接
});

2. 三者对比

方法	返回值	适用场景
serialize()	URL 编码字符串	直接 AJAX 提交表单（最常用）
serializeArray()	键值对象数组	需要遍历、修改、转 JSON
原生 FormData	表单对象	上传文件 + 表单一起提交

注意：上传文件不能用 serialize() ，必须用 FormData。

---

七、常见问题 & 踩坑总结

1. 参数丢失？ 90% 原因：标签没加 name 属性。

2. 中文乱码？ serialize() 默认 UTF-8 URL 编码，后端正常接收解码即可； 若乱码，检查页面编码、后端接收编码是否统一。

3. 复选框/多选框只拿到一个值？ 正常，同 name 多选会生成多个 name=value，后端用数组接收。

4. 动态添加的表单元素序列化不到？ 只要元素有 name，序列化时存在就能正常获取，和绑定事件不一样，不需要事件委托。

5. 不想序列化某个字段？

   • 移除 name
   • 给元素加 disabled
   • 提交前手动删除字段

6. 不能上传文件 serialize() 不处理 file 类型，文件上传改用：

   var fd = new FormData($("#form1")[0]);

---

八、一句话速记

1. serialize() → 表单转 URL 参数字符串，AJAX 提交表单首选；
2. 核心前提：必须有 name 属性；
3. 禁用元素忽略、隐藏元素正常序列化；
4. 需要改数据/转对象，用 serializeArray()；
5. 传文件不用它，改用原生 FormData。