菜鸟教程
Reference Web API reference

URLSearchParams 参考

URLSearchParams 用于处理 URL 查询参数，适合读取 location.search、构造接口查询字符串或把对象转换为查询参数。

语法

js 
const params = new URLSearchParams(search);

常用方法

方法 说明
get(name) 读取第一个同名参数
getAll(name) 读取全部同名参数
set(name, value) 设置参数，会覆盖同名旧值
append(name, value) 追加参数，允许同名多值
delete(name) 删除参数
has(name) 判断参数是否存在
toString() 序列化为查询字符串

返回值

多数读取方法返回字符串、字符串数组或布尔值；修改方法通常直接改变当前 URLSearchParams 实例。

示例

js 
const params = new URLSearchParams("q=js&page=1");

params.set("page", "2");
params.append("tag", "web-api");

console.log(params.get("q"));
console.log(params.toString());

可运行演示

在线代码演示
源码 
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>URLSearchParams 演示</title>
    <style>
      * { box-sizing: border-box; }
      body { margin: 0; padding: 24px; font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #0f172a; background: #f8fafc; }
      .demo { max-width: 760px; margin: 0 auto; padding: 20px; border: 1px solid #dbeafe; border-radius: 12px; background: #ffffff; }
      .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }
      label { display: grid; gap: 6px; font-weight: 600; }
      input { padding: 10px; border: 1px solid #cbd5e1; border-radius: 8px; font: inherit; }
      code { display: block; margin-top: 16px; padding: 12px; border-radius: 8px; background: #eff6ff; color: #1e3a8a; overflow-wrap: anywhere; }
    </style>
  </head>
  <body>
    <main class="demo">
      <div class="grid">
        <label>关键词<input id="q" value="javascript"></label>
        <label>页码<input id="page" value="2"></label>
        <label>标签<input id="tag" value="web-api"></label>
      </div>
      <code id="output"></code>
    </main>
    <script>
      const fields = [...document.querySelectorAll("input")];
      const output = document.querySelector("#output");
      function render() {
        const params = new URLSearchParams();
        params.set("q", document.querySelector("#q").value);
        params.set("page", document.querySelector("#page").value);
        params.append("tag", document.querySelector("#tag").value);
        output.textContent = "/search?" + params.toString();
      }
      fields.forEach((field) => field.addEventListener("input", render));
      render();
    </script>
  </body>
</html>

常见错误

  • get() 只返回第一个同名参数；数组类参数应使用 getAll() 或约定自己的编码格式。
  • toString() 返回值不包含开头的 ?，拼接 URL 时需要自己加。
  • 查询参数都是字符串，数字和布尔值读取后要自己转换。

相关内容

相关内容