如何获取 URL 参数:原生 API、工具库与路由的选型(2):路由状态与 URL 的持续同步
- 参数语义与解析器选择
- 路由状态与 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 和页面状态是否保持一致。自定义解析器、数组格式和默认值都应同时验证读取与写回;类型提示不能代替业务校验。
上一篇:参数语义与解析器选择。