# URLSearchParams 参考

URL: https://caijiao.org/reference/web-api/urlsearchparams
Source: docs/reference/web-api/urlsearchparams.md
Description: URLSearchParams Reference，整理查询参数读取、追加、修改、删除、序列化、可运行演示和常见错误。

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());
```

## 可运行演示

[在线代码演示](/web-api/demos/urlsearchparams-builder.html)

## 常见错误

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

## 相关内容

- [Web API Reference](/reference/web-api/)
- [URL API](/reference/web-api/url)
- [URLSearchParams.prototype.get 参考](/reference/javascript/urlsearchparams-get)
- [JavaScript 如何获取 URL 参数](/how-to/javascript/get-url-params)
- [JavaScript 如何把对象转成查询字符串](/how-to/javascript/object-to-query-string)
- [URL Encoder / Decoder](/tool/url-encoder-decoder)
- [MDN URLSearchParams](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)