arkts-qs

A querystring parser and stringifier for HarmonyOS ArkTS — ported from qs v6.15.2. Provides parse() and stringify() with full options support, nested object handling, and prototype pollution protection.

特性

• 🔍 parse / stringify — 完整的查询字符串解析和序列化
• 📦 嵌套对象 — 支持 bracket 和 dot 两种嵌套语法
• 🔢 数组格式 — indices, brackets, repeat, comma 四种格式
• 🛡️ 原型污染防护 — 默认开启 protoGuard
• 🌐 RFC 1738 / RFC 3986 — 两种编码格式
• 🔧 零依赖 — 纯算法实现

安装

ohpm install @ohos/arkts-qs

或本地依赖：

// entry/oh-package.json5
{
  "dependencies": {
    "library": "file:../library"
  }
}

快速开始

import { parse, stringify } from 'library';

// 解析
parse('a[0]=b&a[1]=c');
// → { a: ['b', 'c'] }

parse('user[name][first]=John&user[email]=john@example.com');
// → { user: { name: { first: 'John' }, email: 'john@example.com' } }

// 序列化
stringify({ a: { b: 'c' } });
// → 'a%5Bb%5D=c'

stringify({ a: ['b', 'c', 'd'] }, { arrayFormat: 'indices' });
// → 'a[0]=b&a[1]=c&a[2]=d'

stringify({ a: ['b', 'c'] }, { arrayFormat: 'brackets' });
// → 'a[]=b&a[]=c'

stringify({ a: ['b', 'c'] }, { arrayFormat: 'comma' });
// → 'a=b,c'

API

parse(str: string, options?: ParseOptions): Record<string, Object>

选项	类型	默认值	说明
allowDots	boolean	false	是否允许点分隔的 key
allowEmptyArrays	boolean	false	是否允许空数组 a[]
allowPrototypes	boolean	false	是否允许覆盖 __proto__
allowSparse	boolean	false	稀疏数组（跳过未定义索引）
arrayLimit	number	20	最大数组长度
charset	string	'utf-8'	字符编码
charsetSentinel	boolean	false	是否检测 charset sentinel
comma	boolean	false	逗号分隔值
delimiter	string	'&'	分隔符
depth	number	5	最大嵌套深度
ignoreQueryPrefix	boolean	false	忽略 ? 前缀
parameterLimit	number	1000	最大参数数量
parseArrays	boolean	true	是否解析数组
plainObjects	boolean	false	返回普通对象（无原型）
strictNullHandling	boolean	false	严格 null 处理

stringify(obj: Object, options?: StringifyOptions): string

选项	类型	默认值	说明
addQueryPrefix	boolean	false	添加 ? 前缀
allowDots	boolean	false	点分隔嵌套 key
allowEmptyArrays	boolean	false	允许空数组
arrayFormat	string	'indices'	数组格式: indices / brackets / repeat / comma
charset	string	'utf-8'	字符编码
delimiter	string	'&'	分隔符
encode	boolean	true	是否编码
encodeValuesOnly	boolean	false	仅编码 value
format	string	'RFC3986'	RFC1738 或 RFC3986
skipNulls	boolean	false	跳过 null 值
sort	(a,b) => number	—	key 排序函数
strictNullHandling	boolean	false	严格 null 处理

项目结构

qs-arkts/
├── library/                       # HAR 库模块
│   └── src/main/ets/
│       ├── Index.ets              # 桶导出
│       ├── types.ets              # 类型定义
│       ├── parse.ets              # 查询字符串解析
│       ├── stringify.ets          # 查询字符串序列化
│       ├── formats.ets            # RFC 1738 / RFC 3986 格式化
│       ├── proto_guard.ets        # 原型污染防护
│       ├── side_channel.ets       # 内部状态通道
│       ├── utils_encode.ets       # 字符编码工具
│       └── utils_merge.ets        # 深度合并工具
└── entry/                         # 测试入口模块
    └── src/main/ets/pages/
        └── Index.ets              # 测试用例

与 qs 的区别

qs (JavaScript)	arkts-qs (ArkTS)
Node.js Buffer + iconv 编码	HarmonyOS util.TextEncoder/TextDecoder
getEncoder() / getDecoder() factory	内联工具函数
hasOwnProperty 原型方法	hasOwnProp() 安全替代

许可证

BSD 3-Clause — 与原 qs 保持一致。

致谢

• qs by Nathan LaFreniere — 原创 JavaScript 查询字符串库