207 lines
5.3 KiB
Markdown
207 lines
5.3 KiB
Markdown
|
---
|
|||
|
|
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. **兼容性**：确保在支持的浏览器环境中使用，现代浏览器都支持
|