---
name: jjb-common-lib-qs
description: 定义 @cqsjjb/jjb-common-lib qs 模块使用规范。在解析/序列化 URL 查询字符串、与 tools.router 结合时查阅。
---

# qs 模块使用规范

## 概述

`qs` 模块是 `@cqsjjb/jjb-common-lib` 通用工具库中的查询字符串工具模块，用于处理 URL 查询字符串的解析和序列化。`tools.router` 的核心技术基于此 `qs` 模块实现。

### 导入方式

```javascript
import { qs } from '@cqsjjb/jjb-common-lib';
```

## 内置方法详解

### parse(url)

解析 URL，获取 query 参数对象。

**参数：**
- `url` (string): 待解析的 URL 字符串

**返回值：**
- `Record<string, string>`: 解析后的 query 对象

**示例：**
```javascript
import { qs } from '@cqsjjb/jjb-common-lib';

// 解析完整 URL
qs.parse("http://xxx.com?a=1&b=2")
// => { a: "1", b: "2" }

// 解析带查询字符串的 URL
qs.parse("https://example.com/search?keyword=test&page=1")
// => { keyword: "test", page: "1" }

// 解析只有查询字符串的部分
qs.parse("?name=张三&age=25")
// => { name: "张三", age: "25" }
```

**注意事项：**
- 返回的对象中，所有值都是字符串类型
- 如果 URL 中没有查询参数，返回空对象 `{}`
- 如果 URL 格式不正确，可能返回空对象或部分解析结果

### stringify(query, prefix?)

将对象序列化为 query string。

**参数：**
- `query` (Record<string, string | number | boolean>): 待序列化的对象
- `prefix` (boolean, 可选): 是否加上前缀 `?`，默认为 `true`

**返回值：**
- `string | undefined`: 序列化后的 query string，若对象为空返回空字符串或 `undefined`

**示例：**
```javascript
import { qs } from '@cqsjjb/jjb-common-lib';

// 基本用法（默认带 ? 前缀）
qs.stringify({ a: 1, b: 2 })
// => "?a=1&b=2"

// 不带前缀
qs.stringify({ a: 1, b: 2 }, false)
// => "a=1&b=2"

// 字符串值
qs.stringify({ name: "张三", age: "25" })
// => "?name=张三&age=25"

// 布尔值
qs.stringify({ active: true, deleted: false })
// => "?active=true&deleted=false"

// 数字值
qs.stringify({ page: 1, pageSize: 10 })
// => "?page=1&pageSize=10"

// 空对象
qs.stringify({})
// => "" 或 undefined
```

**注意事项：**
- 对象的值可以是 `string`、`number` 或 `boolean` 类型
- 默认会添加 `?` 前缀，如果不需要前缀，传入 `false`
- 如果对象为空，返回空字符串或 `undefined`

## 使用场景

### 解析 URL 参数

```javascript
// 从当前 URL 获取参数
const params = qs.parse(window.location.href);
console.log(params.id); // 获取 id 参数

// 从完整 URL 解析参数
const url = "https://example.com/user?id=123&name=张三";
const query = qs.parse(url);
console.log(query.id);   // "123"
console.log(query.name); // "张三"
```

### 构建查询字符串

```javascript
// 构建查询字符串用于跳转
const query = {
  page: 1,
  pageSize: 10,
  keyword: "搜索关键词"
};
const queryString = qs.stringify(query);
window.location.href = `/list${queryString}`;

// 构建不带前缀的查询字符串
const params = qs.stringify({ id: 123 }, false);
// => "id=123"
```

### 与路由结合使用

```javascript
// 解析路由参数
const routeParams = qs.parse(window.location.search);

// 更新路由参数
const newParams = {
  ...routeParams,
  page: 2
};
const newQuery = qs.stringify(newParams);
window.history.pushState({}, '', `${window.location.pathname}${newQuery}`);
```

### 与 tools.router 结合

`qs` 模块是 `tools.router` 的核心实现基础：

```javascript
import { tools } from '@cqsjjb/jjb-common-lib';

// tools.router 内部使用 qs 模块处理查询字符串
// 获取当前路由参数
const params = tools.router.query;
// 等同于解析 window.location.search

// 设置路由参数
tools.router.query = { id: 123 };
// 内部会使用 qs.stringify 序列化参数
```

## 常见问题

### 中文编码问题

如果 URL 中包含中文字符，浏览器会自动进行编码/解码，`qs` 模块会正确处理：

```javascript
// 浏览器会自动编码中文
qs.parse("http://example.com?name=张三")
// => { name: "张三" } （浏览器已自动解码）

// 序列化时，浏览器会自动处理编码
qs.stringify({ name: "张三" })
// => "?name=张三" （浏览器会自动编码为 %E5%BC%A0%E4%B8%89）
```

### 特殊字符处理

```javascript
// 特殊字符会被正确编码
qs.stringify({ search: "hello world" })
// => "?search=hello%20world"

qs.parse("?search=hello%20world")
// => { search: "hello world" }
```

### 数组参数

注意：当前版本的 `qs` 模块可能不支持数组参数的解析和序列化，如果需要处理数组参数，建议使用 `tools.router` 或手动处理。

## 相关模块

- **tools.router**：路由参数管理对象，基于 `qs` 模块实现
- **详细文档**：参考 `reference/qs.d.ts` 查看完整的类型定义和 API 文档

## 注意事项

1. **类型转换**：`parse` 方法返回的所有值都是字符串类型，需要数字或布尔值时需要手动转换

2. **空值处理**：空对象序列化时可能返回空字符串或 `undefined`，使用时需要注意判断

3. **URL 编码**：浏览器会自动处理 URL 编码/解码，通常不需要手动处理

4. **兼容性**：确保在支持的浏览器环境中使用，现代浏览器都支持