jQuery param()方法：将对象或数组序列化为查询字符串-代码号

在前端与后端通信时，GET 请求常常需要把数据拼接在 URL 的查询字符串中。手动拼接参数既繁琐又容易出错——你需要处理特殊字符的编码、数组的表示方式、嵌套对象的展开格式等。jQuery 的 $.param() 方是为了解决这个问题而存在的：它能将一个 JavaScript 对象或数组自动转换为规范编码的查询字符串。

这个方法返回的字符串可以直接追加到 URL 后面，也可以通过 AJAX 的 data 参数间接使用。实际上，当你给 $.get() 或 $.ajax() 传入一个对象作为 data 时，jQuery 内部就是调用 $.param() 来做序列化的。

为什么我习惯用 $.param() 而不是手动拼接查询字符串？

手动拼接 URL 参数时，有两类问题容易反复出现。一是编码问题：中文、空格、特殊符号需要调用 encodeURIComponent()，稍不留神就会遗漏。二是嵌套结构的处理：当对象里还包含对象或数组时，参数名应该如何展开并没有一个直觉上的唯一答案。$.param() 同时解决了这两层问题，编码自动完成，嵌套结构也有明确的序列化规范。除非你在处理极简单的平铺键值对，否则用 $.param() 的可靠性和效率都更高。

语法

$.param(obj, trad)

参数说明：

obj（必需）：要被序列化的对象或数组。这是数据源。
trad（可选）：布尔值，指定是否使用传统风格的序列化方式。所谓传统风格，指的是 jQuery 1.4 之前的序列化规则，主要区别在于对嵌套对象的处理方式。如果你的后端接口是对应老旧模式开发的，可能需要开启这个参数。对于大多数现在项目，保持默认 false 即可。

课程知识要点

自动 URL 编码：$.param() 输出的字符串已经经过 encodeURIComponent() 处理，可以直接用于 URL 查询字符串或 AJAX 请求的 data 字段。
嵌套对象的序列化：默认情况下，嵌套对象会用方括号展开，如 a[b]=1&a[c]=2。数组则会生成带索引的形式。
传统模式兼容：当 trad 设为 true 时，序列化风格会发生变化，主要面向需要兼容老版本 jQuery 或特定后端解析规则的场景。
返回值是字符串：返回的就是可以直接拼接在 URL ? 后面的查询字符串格式，无需二次处理。

示例一：将普通对象序列化为查询字符串

这个例子展示最基础的用法——把一个包含学生信息的对象转换为查询字符串，并显示在页面上。

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>param() 基础序列化 · 编程学习</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
</head>
<body>
    <h2>jQuery param() 方法——对象序列化</h2>
    <p>点击按钮，将学生信息对象转换为查询字符串：</p>
    <button>生成查询字符串</button>
    <p id="output"></p>

    <script>
        $(document).ready(function () {
            // 构建一个学生信息对象
            var student = {
                name: "李明",
                rollNo: "19",
                grade: "四年级",
                email: "alan@ebingou.cn"
            };

            $("button").click(function () {
                // 序列化为查询字符串
                var queryString = $.param(student);
                $("#output").text(queryString).css("fontSize", "20px");
            });
        });
    </script>
</body>
</html>

点击按钮后，你会看到类似这样的输出：name=%E6%9D%8E%E6%98%8E&rollNO.19&grade=%E5%9B%9B%E5%B9%B4%E7%BA%A7&email=alan%40ebingou.cn。中文字符和 @ 符号都被正确编码了，不需要手动调用 encodeURIComponent()。

示例二：序列化包含嵌套对象和数组的复杂结构

当数据不只是简单键值对，还包含嵌套对象和数组时，$.param() 的处理能力就体现出来了。下面的例子序列化了两个复杂对象，并用 decodeURIComponent() 解码后展示，方便看清结构。

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>param() 复杂结构序列化 · 编程学习</title>
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.5.1/jquery.min.js"></script>
</head>
<body>
    <h2>jQuery param() 方法——复杂对象序列化</h2>
    <p>点击按钮，查看嵌套对象和数组的序列化结果：</p>
    <button>序列化复杂对象</button>
    <p id="output1"></p>
    <p id="output2"></p>

    <script>
        $(document).ready(function () {
            // 对象一：包含数组
            var obj1 = {
                course: "编程入门",
                modules: [1, 2, 3]
            };

            // 对象二：包含嵌套对象和数组
            var obj2 = {
                course: "前端进阶",
                details: { chapter: 1, page: 2, exercise: 3 },
                tags: ["JavaScript", "Vue"]
            };

            $("button").click(function () {
                // 序列化并解码，便于阅读
                var result1 = decodeURIComponent($.param(obj1));
                var result2 = decodeURIComponent($.param(obj2));

                $("#output1").text("对象一结果: " + result1).css("fontSize", "18px");
                $("#output2").text("对象二结果: " + result2).css("fontSize", "18px");
            });
        });
    </script>
</body>
</html>

点击按钮后，对象一的输出类似 course=编程入门&modules%5B%5D=1&modules%5B%5D=2&modules%5B%5D=3（解码后是 modules[]=1&modules[]=2&modules[]=3），数组被自动展开为带方括号的多个键值对。对象二的输出则展示了嵌套对象用 details[chapter]=1&details[page]=2 的形式展开，数组同样正确处理。

在项目中，$.param() 除了直接用于生成查询字符串，还有几个间接用法值得了解。第一，你可以把 $.param() 的结果直接赋给 URL 的 search 部分，配合 window.location 来做页面跳转。第二，如果后端接收的是 application/x-www-form-urlencoded 格式的数据，$.param() 的输出就是标准格式，POST 请求里也能用。

如果你使用的是 jQuery 1.4 之后版本并与比较传统的后端对接，可能会遇到参数名格式不匹配的问题。这时可以尝试把 trad 参数设为 true，传统模式的序列化结果会去掉嵌套对象参数的方括号，输出更像 a.b=1&a.c=2 的风格。这个选项不常用，但遇到兼容性问题时知道它的存在可以省去很多排查时间。

如果项目已经不再依赖 jQuery，现在浏览器也提供了原生的 URLSearchParams 和 Object.entries() 等方式来实现类似功能。但 $.param() 对嵌套结构的处理逻辑仍然是一个不错的参考实现——它定义了数组和嵌套对象的展开规则，了解这个规则对理解 HTTP 请求的数据编码机制很有帮助。

本文标签：