qs

介绍

qs 是一个用于解析和序列化 URL 查询字符串的 JavaScript 库，比原生 URLSearchParams 更灵活，支持嵌套对象、数组格式等。

qs.parse(str)

提示

字符串转对象

基础用法

import qs from 'qs'

const query = 'a=1&b=2'
const obj = qs.parse(query)
// { a: '1', b: '2' }

数组支持（默认支持嵌套）

qs.parse('arr=1&arr=2')
// => { arr: ['1', '2'] }

嵌套对象解析

qs.parse('user[name]=Tom&user[age]=30')
// => { user: { name: 'Tom', age: '30' } }

支持索引数组格式

qs.parse('list[0]=a&list[1]=b')
// => { list: ['a', 'b'] }

qs.stringify(obj)

提示

对象转字符串

基础对象

qs.stringify({ a: 1, b: 2 })
// => 'a=1&b=2'

嵌套对象

qs.stringify({ user: { name: 'Tom', age: 30 } })
// => 'user[name]=Tom&user[age]=30'

数组

qs.stringify({ list: ['a', 'b'] })
// => 'list[0]=a&list[1]=b'

数组格式可选

qs.stringify({ tags: ['js', 'css'] }, { arrayFormat: 'repeat' })
// => 'tags=js&tags=css'

qs.stringify({ tags: ['js', 'css'] }, { arrayFormat: 'brackets' })
// => 'tags[]=js&tags[]=css'

常用配置项

选项名	类型	默认	描述
encode	boolean	true	是否自动对 key/value 编码
arrayFormat	string	'indices'	数组序列化方式（见下）
skipNulls	boolean	false	是否忽略 null 值
addQueryPrefix	boolean	false	是否在前面加上 ?

arrayFormat 的可选值：

• 'indices'：默认，arr[0]=a&arr[1]=b
• 'brackets'：arr[]=a&arr[]=b
• 'repeat'：arr=a&arr=b
• 'comma'：arr=a,b

常见问题

❓ 为什么我用 qs.stringify() 得到的数组是 arr[0]=a&arr[1]=b？

因为默认的 arrayFormat 是 "indices"，可以改为 "brackets" 或 "repeat" 来适配后端格式要求。

❓ undefined 和 null 怎么处理？

默认跳过 undefined，null 会转为空字符串，除非配置 skipNulls: true