5.3 KiB

Raw Blame History

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

qs 模块使用规范

概述

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

导入方式

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

内置方法详解

parse(url)

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

参数：

url (string): 待解析的 URL 字符串

返回值：

Record<string, string>: 解析后的 query 对象

示例：

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

示例：

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 参数

// 从当前 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); // "张三"

构建查询字符串

// 构建查询字符串用于跳转
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"

与路由结合使用

// 解析路由参数
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 的核心实现基础：

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 模块会正确处理：

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

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

特殊字符处理

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

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

数组参数

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

注意事项

类型转换：parse 方法返回的所有值都是字符串类型，需要数字或布尔值时需要手动转换
空值处理：空对象序列化时可能返回空字符串或 undefined，使用时需要注意判断
URL 编码：浏览器会自动处理 URL 编码/解码，通常不需要手动处理
兼容性：确保在支持的浏览器环境中使用，现代浏览器都支持

5.3 KiB Raw Blame History Unescape Escape