前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载vueuse/router 是 VueUse 官方为 vue-router 提供的扩展包add-on它将route.hash、route.params、route.query封装为可直接读写的响应式Ref读取时自动同步当前路由写入时自动调用router.replace()/router.push()更新 URL。本指南以仓库中的 packages/router/README.md 为骨架结合三个工具的源码useRouteHash、useRouteParams、useRouteQuery与测试用例完整讲解安装、API 用法、双向数据转换、默认值行为以及底层响应式实现原理帮助你把这套工具直接落地到自己的 Vue 3 项目中。安装与包结构vueuse/router的 peer 依赖为vue^3.5.0与vue-router^4.0.0 || ^5.0.0安装命令如下npm i vueuse/router vue-router5vue-router可以是 4.x 或 5.x文档示例以 5 为主包本身只依赖vueuse/shared仓库内部共享工具包无其他运行时依赖并声明sideEffects: false可安全参与 Tree Shaking构建产物通过tsdown生成入口与类型定义均指向dist目录见 package.json。包内共导出 3 个函数统一从入口 packages/router/index.ts 转发函数作用文档useRouteQuery响应式的route.query查询字符串参数useRouteQuery/index.mduseRouteParams响应式的route.params路径动态段参数useRouteParams/index.mduseRouteHash响应式的route.hashURL 锚点useRouteHash/index.md三者拥有统一的选项类型ReactiveRouteOptions与ReactiveRouteOptionsWithTransform定义在 packages/router/_types.ts 中export interface ReactiveRouteOptions { /** 更新模式默认 replace也支持 Ref 动态切换 */ mode?: MaybeRefreplace | push /** 未传入时自动 useRoute() */ route?: ReturnTypetypeof useRoute /** 未传入时自动 useRouter() */ router?: ReturnTypetypeof useRouter } export interface ReactiveRouteOptionsWithTransformV, R extends ReactiveRouteOptions { transform?: | ((val: V) R) | ({ get?: (value: V) R; set?: (value: R) V }) }useRouteQuery把 URL 查询参数变成响应式 RefuseRouteQuery(name, defaultValue?, options?)返回绑定到指定 query 键的Ref读取时返回route.query[name]赋值时自动更新 URLimport { useRouteQuery } from vueuse/router const search useRouteQuery(search) const search useRouteQuery(search, foo) // 带默认值 const page useRouteQuery(page, 1, { transform: Number }) // 带转换 console.log(search.value) // route.query.search search.value foobar // router.replace({ query: { search: foobar } })导航模式replace 与 push默认情况下写入会使用router.replace()即替换当前历史记录、URL 不留痕。如果你希望每次修改都新增一条历史记录配合浏览器后退键可传入mode: pushconst search useRouteQuery(search, , { mode: push })从源码看mode支持MaybeRef即可以传ref(push)实现运行期动态切换最终通过routertoValue(mode)调用对应方法见 useRouteQuery/index.ts。双向转换transform 的 get / settransform可以是一个纯函数如Number也可以是一个同时提供get与set的对象分别负责「从 URL 读值时转换」与「写入 URL 前转换」。典型的场景是把逗号分隔的字符串与数组互相转换const filters useRouteQuery(filters, [], { transform: { get: v v ? v.split(,) : [], set: v v.join(,), }, }) // 读取URL 中 a,b,c - [a, b, c] // 写入[a, b, c] - URL 中 a,b,c更复杂的场景例如把 URL 中的 JSON 字符串与对象互转也有对应的测试用例验证见 useRouteQuery/index.test.tsconst object useRouteQuery(serialized, undefined, { transform: { get: (value: string) JSON.parse(value), set: (value: any) JSON.stringify(value), }, }) object.value { foo: baz } // 写回 URL 时变为 {foo:baz}注意get与set均是可选的只提供其中一个也能正常工作测试中专门验证了仅提供get的场景见 useRouteQuery/index.test.ts。默认值行为等于默认值时从 URL 移除当写入的值与默认值相同时对应 query 参数会被从 URL 中移除而不是写入默认值本身const page useRouteQuery(page, 1) page.value 2 // URL: ?page2 page.value 1 // URL: page 参数被移除因为等于默认值这一逻辑在源码set中体现为query (v toValue(defaultValue)) ? undefined : v见 useRouteQuery/index.ts默认值支持MaybeRefOrGetter会在每次比较与读取时动态求值。useRouteParams绑定路径动态段参数useRouteParams(name, defaultValue?, options?)与useRouteQuery的用法完全对称只不过数据源是route.params路径参数如/user/:userId中的userIdimport { useRouteParams } from vueuse/router const userId useRouteParams(userId) const userId useRouteParams(userId, -1) // 带默认值 const userId useRouteParams(page, 1, { transform: Number }) // 带转换 console.log(userId.value) // route.params.userId userId.value 100 // router.replace({ params: { userId: 100 } })在源码实现上useRouteParams/index.ts读取时不仅判空param ! undefined还会过滤空字符串param ! 才回退到默认值写入时值等于默认值或为null时对应参数会被置为undefined并写入导航目标实现「清除参数」的效果。transform、mode等选项与useRouteQuery完全一致同样支持get/set双向转换。useRouteHash响应式操作 URL 锚点useRouteHash(defaultValue?, options?)是最简洁的一个它不需要参数名直接把整个route.hash暴露为Refimport { useRouteHash } from vueuse/router const search useRouteHash() console.log(search.value) // route.hash search.value foobar // router.replace({ hash: foobar })实现上useRouteHash/index.ts使用模块级变量_hash缓存当前值get返回_hash || toValue(defaultValue)即「有真实 hash 优先返回 hash否则返回默认值」set时若赋值为null则视为清除锚点_hash undefined并整体保留当前的params与query只更新hash因此修改锚点不会影响其他路由字段。底层原理customRef 批量队列 同步 watch三个工具的核心机制完全一致理解 useRouteQuery/index.ts 的源码即可举一反三customRef 构建代理通过customRef自定义get/set的响应式行为get时track()收集依赖并应用transformGetset时先经transformSet转换、再trigger()通知更新按 Router 维度的批量队列源码中const _queue new WeakMapRouter, Mapstring, any()为每个router实例维护一个Map。在同一个 tick 内对多个 query 键赋值会被暂存进队列随后在nextTick中合并成一次导航调用routertoValue(mode)避免频繁触发路由跳转见 useRouteQuery/index.ts。useRouteParams使用同名的_queue弱映射实现等价效果同步 watch 反向同步通过watch(() route.query[name], ..., { flush: sync })监听路由变化例如用户手动修改 URL、点击浏览器前进后退一旦路由外部变更立即更新内部缓存并_trigger()刷新 Ref保证「双向绑定」——无论从代码赋值还是从地址栏改动Ref的值始终与路由保持一致作用域自动清理利用tryOnScopeDispose在组件/副作用作用域销毁时清空缓存值避免组件卸载后残留的引用造成内存泄漏见 useRouteQuery/index.ts。这一机制同样被仓库中的单元测试覆盖测试通过 mock 的routereactive对象与router仅含replace方法的对象验证了默认值读取、transform转换、批量写入等行为见 useRouteQuery/index.test.ts你也可以参考这些用例在本地快速验证行为。常见场景小结搜索筛选页useRouteQuery(keyword)useRouteQuery(page, 1, { transform: Number })配合mode: push让筛选条件可被浏览器后退还原且参数可分享、可收藏详情页参数useRouteParams(userId, { transform: Number })直接得到数字类型的响应式参数配合watch在参数变化时重新拉取数据锚点定位useRouteHash()绑定 Tab 或滚动位置修改value即可更新 URL 锚点且不影响 query 与 params复杂状态序列化利用transform.get/set把数组、对象等结构化数据序列化到 URL实现「URL 即状态」的表单/过滤器同步方案。以上用法均基于仓库当前源码vueuse/router版本 15.0.0验证适用于 Vue 3.5 与 vue-router 4.x / 5.x 项目。赞分享前端【免费下载链接】vueuseCollection of essential Vue Composition Utilities for Vue 3项目地址https://gitcode.com/gh_mirrors/vu/vueuse点击查看免费下载相关推荐json-render 的 shadcn/ui 组件库json-render/shadcn 实战指南json render 的 shadcn/ui 组件库json render/shadcn 实战指南 本指南以 json render/shadcn 包的前端airi 前端响应式流实战用 VueUse toObserver 让 RxJS Observable 直接写入 Vue refairi 前端响应式流实战用 VueUse toObserver 让 RxJS Observable 直接写入 Vue ref toObserver 是 VuAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染VueUse vueuse/math 之 logicNot为 ref 提供响应式 NOT 逻辑判断的完整实战指南VueUse vueuse/math 之 logicNot为 ref 提供响应式 NOT 逻辑判断的完整实战指南 logicNot 是 VueUse 数学扩前端上一篇AgentScope 2.0构建可观测、可理解、可信赖的智能体框架下一篇setup-node培训材料教学视频与文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考