React Router setSearchParams如何实现数组搜索参数逗号分隔

react-router 自带的 setSearchParams 底层遵循标准 URLSearchParams 行为，传入数组类型值时默认会生成多个同名键参数，要改成逗号拼接的单键值格式，手动预处理入参即可，不需要额外引入依赖。

具体实现步骤 #

1. 写入参数时预处理数组值 #

不要直接把原始状态对象传入 setSearchParams，先遍历对象将所有数组类型的值用逗号拼接为字符串，再传入方法：

// 你的原始状态对象
const filterState = {
  marca: 'AUDI',
  modello: 'A4',
  categoria: ['Aziendale', 'Nuovo']
}

// 预处理参数：数组转逗号拼接字符串
const processedParams = Object.fromEntries(
  Object.entries(filterState).map(([key, value]) => [
    key,
    Array.isArray(value) ? value.join(',') : value
  ])
)

// 传入处理后的参数
setSearchParams(processedParams)

执行后生成的URL搜索参数即为你期望的格式：?categoria=Aziendale,Nuovo&marca=AUDI&modello=A4

2. 读取参数时还原数组类型 #

因为存储时数组被转为了逗号分隔的字符串，读取参数时需要手动把对应字段拆分数组，避免拿到字符串无法直接使用：

const [searchParams] = useSearchParams()

const filterState = {
  marca: searchParams.get('marca'),
  modello: searchParams.get('modello'),
  // 拆分逗号分隔值，空值兜底为空数组
  categoria: searchParams.get('categoria')?.split(',') || []
}

通用逻辑封装 #

如果项目中多处用到这类参数格式，可以封装通用的序列化、解析方法，避免重复写转换逻辑：

/**
 * 序列化参数：数组转逗号拼接字符串
 * @param {Record<string, string | number | string[]>} paramsObj 原始参数对象
 * @returns 适配setSearchParams的参数对象
 */
export const buildSearchParams = (paramsObj) => {
  return Object.fromEntries(
    Object.entries(paramsObj).map(([key, value]) => [
      key,
      Array.isArray(value) ? value.join(',') : value
    ])
  )
}

/**
 * 解析URL参数：指定字段还原为数组
 * @param {URLSearchParams} searchParams useSearchParams返回的实例
 * @param {string[]} arrayKeys 需要转成数组的字段名列表
 * @returns 解析后的状态对象
 */
export const parseSearchParams = (searchParams, arrayKeys = []) => {
  const result = {}
  for (const [key, value] of searchParams.entries()) {
    result[key] = arrayKeys.includes(key) ? value.split(',') : value
  }
  return result
}

封装后使用示例：

// 写入参数
setSearchParams(buildSearchParams(filterState))

// 读取参数
const filterState = parseSearchParams(searchParams, ['categoria'])

注：URL规范本身没有对数组类型搜索参数的统一标准，多同名键、逗号拼接、方括号标记（如categoria[]=xxx）都是常见实现，手动转换的方式兼容所有react-router版本，没有额外依赖风险。

内容的提问来源于stack exchange，提问作者Attilio Iurlaro