跳到正文

如何获取 URL 参数:原生 API、工具库与路由的选型(2):路由状态与 URL 的持续同步

如何获取 URL 参数:原生 API、工具库与路由的选型

  1. 参数语义与解析器选择
  2. 路由状态与 URL 的持续同步(当前)

读取 query 只是开始。筛选、分页和视图状态持续变化时,URL、组件状态与浏览器前进后退还要保持一致。这里讨论 Vue Router 的 query 从哪里来,以及 VueUse、nuqs 和 TanStack Router 怎样承担同步职责。重复字段、空值、编码和各解析器的对照见第一篇。版本与实验条件仍沿用 2026-10-18 的记录。

Vue Router 的 this.$route.query 从哪里来

Vue Router 把地址解析结果放进路由状态,组件读取这份状态。它还负责导航、响应式更新、history / hash 等路由层行为,业务页面通常不需要再解析一次 location.search。

默认解析器与路由状态

Vue Router 3.6.5 的 src/util/query.js已经有自己的 query 解析器,会处理加号、百分号、无等号参数和重复 key,并允许通过配置替换。它没有在这里调用 qs 或 query-string。

Vue Router 4.x,以及当前 5.4.0 的普通 createRouter() 路径,也使用自己的解析与序列化函数。5.4.0 的 router.ts中,选择函数的关键两行是:

// packages/router/src/router.ts:156
const parseQuery = options.parseQuery || originalParseQuery;
const stringifyQuery = options.stringifyQuery || originalStringifyQuery;

字符串地址经 parseURL()分离 path、query、hash,query 再交给这个解析函数。默认 query.ts用下面的表达式区分无等号和空字符串:

// packages/router/src/query.ts:65
const value = eqPos < 0 ? null : decode(searchParam.slice(eqPos + 1));

同一个 key 第一次出现时保存单值,再出现时转成数组并继续追加。对 /search?tag=js&tag=ts&flag&empty=,普通路由的结果是:

route.query.tag; // ['js', 'ts']
route.query.flag; // null
route.query.empty; // ''
route.query.missing; // undefined

导航确认后,解析出的目标路由写入 currentRoute。安装到 Vue 应用时,$route 的 getter 返回 unref(currentRoute);Composition API 的 useRoute() 则读取注入的响应式路由对象。因此 this.$route.query 是当前路由状态的一部分,并不是每次访问属性时都重新拆地址。

读取单值时要处理数组和空值,不能用 as string 消除类型提示后就认为数据可靠。路由参数变化时也应重新校验,例如在 computed() 中派生当前页码,或 watch 对应字段。修改 URL 使用 router.push() / router.replace(),让路由状态与导航保持一致;直接修改 route.query 不能替代导航。

Vue Router 5.4.0 另有实验路由 API,它让出现的 query 字段统一使用数组,单值也会成为 ['vue'],无等号参数成为 [null]。这与普通 createRouter() 的模型不同;升级或阅读新文档时,要同时确认版本和所使用的入口。

替换 parseQuery 会改变项目协议

路由配置允许自定义 parseQuery 和 stringifyQuery,这适合已有特殊数组或嵌套协议的项目。但直接把 qs.parse 填进去,会让 filter[status] 从平面字符串 key 变成对象,超出普通 LocationQuery 的值域;只加类型断言会掩盖这种变化。

若确实要支持嵌套 query,需要同时设计解析、序列化、类型和业务归一化,而不是让不同页面自己猜对象形态。只替换一端,还会让「复制 URL 后刷新」与「对象形式的 router.push」表现不同。Vue Router 3 的 stringifyQuery 返回值包含前导 ?,4 / 5 普通路由的函数则不包含;跨版本移植自定义函数时也要核对这个接口区别。

页面只是需要多选标签时,默认重复 key 已经够用:

router.replace({
  query: { ...route.query, tag: ['js', 'ts'], page: '1' },
});

这里使用普通路由模型。是否保留其他字段由页面决定;切换筛选项时是否重置页码,也属于页面协议。

参数还需要持续同步时,还有哪些选择

读取一个 id 后发起请求,通常只需要解析。可如果页面的标签、筛选条件或视图模式会不断变化,还希望这些状态体现在 URL 中,就要同时处理读写、浏览器前进后退、类型转换和默认值。这个需求催生了一类 URL 状态工具,它们在解析器之上增加了框架集成。

VueUse:响应式 URLSearchParams

Vue 项目中的 useUrlSearchParams 会返回响应式参数对象,修改属性时可以写回 URL。它区分 history、hash 和 hash-params 三种模式,分别适配浏览器查询串、Hash 路由内的查询串和直接存参数的 hash。

它的实现以 URLSearchParams 读写参数,并增加响应式状态和 history 更新。因此,适合已有 VueUse、又需要轻量同步页面状态的场景。已经由 Vue Router 管理的参数,默认继续使用路由状态和导航 API,让同一份 URL 状态有一个明确的管理入口。

nuqs:React 中的 URL 状态

nuqs 提供类似 React useState 的 useQueryState() 和 useQueryStates(),把状态保存在 query 中,并通过 parser 定义字符串、整数、布尔值等转换与默认值。它通过框架适配器接入 Next.js、React Router 等环境。

当 React 页面需要长期维护多组 URL 状态时,这类工具可以减少重复的同步代码。仅仅读取外部链接中的一个参数,仍然可以直接用 URLSearchParams。parser 能把字符串转成整数,也不等于自动满足页码范围、重复值策略等业务约束,字段契约仍需明确。

TanStack Router:路由自带结构化 search 参数

TanStack Router 的 search 参数机制采用 JSON-first 的结构化解析,支持把数组、对象等 JSON 可序列化数据写入 query,并通过路由的 validateSearch 定义消费前的校验和类型。

它生成的数组值可以是 JSON 文本,而 qs 常用方括号或重复 key,两者属于不同的 URL 协议。项目已经使用 TanStack Router 时,优先沿用这套能力;与第三方接口交换参数时,仍应遵循接口协议。单纯为了获取 query 而更换路由体系,成本通常过高。

总结

参数持续变化时,读取 query、校验业务值与写回 URL 要使用一致的协议。Vue Router 页面优先使用路由状态和导航 API;VueUse、nuqs 和 TanStack Router 则分别提供对应框架下的同步入口。同一份 URL 状态应有明确的管理者,避免路由与另一套 history 更新逻辑各自写入。

选择同步入口时,可以按当前使用的框架与路由判断:

开发场景 默认选择 需要改变选择的条件
Vue Router 页面读取当前路由参数 route.query / this.$route.query 读取的是另一条 URL,而非当前路由
Vue 页面需要参数与响应式状态同步,已有 VueUse useUrlSearchParams 参数已由 Vue Router 管理时,优先路由状态与导航 API
React 页面需要带类型转换的 URL 状态 nuqs 配合当前框架的 adapter 只读取一次参数时,原生 API 往往已经够用
项目已经使用 TanStack Router 内置 search 解析、序列化与 validateSearch 对接外部接口时,按接口要求使用相应 query 协议

接入后,还要验证筛选与分页变化、复制链接后刷新,以及浏览器前进后退时,URL 和页面状态是否保持一致。自定义解析器、数组格式和默认值都应同时验证读取与写回;类型提示不能代替业务校验。

上一篇:参数语义与解析器选择。