企业官网建设流程全解析

VueUse useUrlSearchParams 指南：在 Vue 3 应用中响应式读写 URL 查询参数

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

导读

useUrlSearchParams是 VueUse 库中面向浏览器（Browser）分类的响应式工具，它将原生 URLSearchParams 为骨架，结合 airi 仓库中真实使用URLSearchParams解析查询串、处理 OAuth 回调、解析桌面悬浮窗参数的源码场景，给出从基础用法、路由模式选择、自定义序列化到类型声明与底层原理的完整实战指南。读完你将能够在任何 Vue 3 / Nuxt 3 项目中用几行代码实现「URL 即状态」的共享、分享与可收藏能力。

为什么需要响应式 URLSearchParams

URL 查询参数是 Web 应用最轻量的「跨页面、可分享、可收藏」状态载体：搜索条件、分页页码、筛选器、来源标识等都可以编码在?foo=bar中。但直接操作原生 API 非常繁琐——你需要手动get/set/toString()，再调用history.replaceState或history.pushState写回地址栏，并且每次还要自行处理变化后的 UI 刷新。

useUrlSearchParams把这一切收敛为一个响应式对象：读取它得到响应式属性，赋值即触发写回，无需任何手动同步代码。这与 VueUse 团队的设计理念一致——正如 SKILL.md 所强调的：优先用 VueUse composable 而非自造轮子，以保持代码简洁、可维护且高性能。

airi 仓库本身就是这一理念的实践者：@vueuse/core以catalog:版本约束被引入到 stage-pocket、stage-tamagotchi、stage-web、ui-server-auth 等多个应用与 stage-layouts、stage-pages 等包中，数十个页面与 composable 直接import { ... } from '@vueuse/core'。useUrlSearchParams在这些场景中正好可以替代大量手写的查询串解析样板代码。

基础用法：history 模式

默认（也是最常见）的模式是history，即查询参数位于 URL 的?之后。调用方式如下：

import { useUrlSearchParams } from '@vueuse/core' const params = useUrlSearchParams('history') console.log(params.foo) // 'bar' params.foo = 'bar' params.vueuse = 'awesome' // url updated to `?foo=bar&vueuse=awesome`

要点拆解：

• useUrlSearchParams('history')返回一个响应式对象，键值对直接对应查询参数；
• 通过params.foo读取当前 URL 中的foo值；
• 对params.foo直接赋值后，地址栏会自动更新为?foo=bar&vueuse=awesome，无需手动调用history.replaceState；
• 未显式指定 mode 时同样按 history 模式处理（mode参数的默认语义即查询串在 search 部分）。

与原生 URLSearchParams 的对照

在useUrlSearchParams内部，get对应原生URLSearchParams.get，set对应原生URLSearchParams.set。airi 仓库中有大量原生 API 的实战用法可供对照：

• 在 window-context.ts 中，渲染进程通过new URLSearchParams(search)解析主进程注入的?synced-leader=false&stage-runtime=minimal查询串，读取synced-leader与stage-runtime两个参数并校验合法性，最终得到渲染器的leadership（leader-only / follower-only）与stageRuntime（full / minimal）运行策略——这正是「查询串驱动初始化配置」的典型场景，若在 Vue 组件内实现，可直接用useUrlSearchParams('history')替换手写解析；
• 在 electron-callback.shared.ts 中，OAuth 登录回调页用searchParams.get('code')、searchParams.get('state')、searchParams.get('error')等解析授权服务器回传的查询参数，并从state中提取端口号与状态值（separatorIndex = fullState.indexOf(':')），其对应的测试用例见 electron-callback.test.ts。

两相对照可以发现：原生方式适合「一次性解析后不再同步」的场景；而useUrlSearchParams的优势在于双向响应式——参数改变立刻反映到响应式对象，响应式对象赋值立刻写回 URL。

Hash Mode：hash 路由下的查询参数

在使用 hash 模式路由（URL 形如#/your/route?...）的应用中，查询参数位于 hash 片段内部。此时需要把mode显式指定为hash：

import { useUrlSearchParams } from '@vueuse/core' const params = useUrlSearchParams('hash') params.foo = 'bar' params.vueuse = 'awesome' // url updated to `#/your/route?foo=bar&vueuse=awesome`

使用hash模式后，赋值的最终落点从?后移到#内的路由路径之后，保证 hash 路由自身的路径结构不被破坏。这非常适合 Vue Router 的createWebHashHistory部署形态（例如静态托管平台上的 SPA 应用），也适合 airi 中依赖 hash 定位初始化路由的场景——在 window-context.ts 中可以看到resolveInitialRendererRoutePath正是从globalThis.location.hash中切出#后的路由路径（#/widgets?source=tray→/widgets），说明该项目的桌面悬浮窗确实以 hash 片段承载路由与来源参数，这与hash模式的应用场景完全吻合。

Hash Params：history 路由 + hash 参数

还有一种混合形态：路由本身使用 history 模式，但希望参数放在#之后而非?之后。此时指定mode为hash-params：

import { useUrlSearchParams } from '@vueuse/core' const params = useUrlSearchParams('hash-params') params.foo = 'bar' params.vueuse = 'awesome' // url updated to `/your/route#foo=bar&vueuse=awesome`

这种模式的价值在于：避免参数出现在请求行（request line）中，从而减少参数被服务器日志、代理与浏览器历史记录完整记录的暴露面，同时仍可利用 hash 变化不会触发整页刷新的特性。airi 的桌面悬浮窗叠加层在判定调试开关时也同时兼顾了 search 与 hash 两处查询串——在 desktop-overlay-polling.ts 中，isOverlayPollHeartbeatEnabled同时构造new URLSearchParams(hashQuery)与new URLSearchParams(locationLike.search)并分别读取心跳参数，其中 hash 侧正是从location.hash内?之后切出的查询串。可见在实际桌面叠加层场景里，参数既可能出现在 search 段也可能出现在 hash 段，history/hash/hash-params三种模式恰好覆盖了这些真实分布。

自定义序列化函数（stringify 选项）

某些场景下默认的URLSearchParams.toString()序列化结果并不符合需求。useUrlSearchParams提供stringify选项，允许完全接管参数的序列化逻辑：

import { useUrlSearchParams } from '@vueuse/core' // Custom stringify function that removes equal signs for empty values const params = useUrlSearchParams('history', { stringify: (params) => { return params.toString().replace(/=(&|$)/g, '$1') } }) params.foo = '' params.bar = 'value' // url updated to `?foo&bar=value` instead of `?foo=&bar=value`

细节说明：

• stringify接收一个URLSearchParams实例，返回序列化后的查询字符串；
• 返回的字符串不应包含开头的?或#，前缀由 composable 按所选 mode 自动拼接；
• 上例通过正则=(&|$)把空值参数的=一并去掉，将?foo=&bar=value压缩为?foo&bar=value，适用于追求 URL 精简或与后端特殊解析约定对齐的场景。

除了stringify，UseUrlSearchParamsOptions还提供以下实用选项（详见 useUrlSearchParams.md 的类型声明）：

这里特别值得关注write与writeMode的组合：write: true（默认）时，每次赋值都会自动写回地址栏；writeMode: 'replace'（默认）不会产生新的历史记录项，适合筛选器、搜索框这类「不希望用户疯狂点返回」的渐进式状态；而writeMode: 'push'则让每次变更都成为一条可返回的历史记录，适合分页切换等需要支持「返回上一页」的交互。若希望得到纯响应式状态、完全由自己控制写回时机，可设置write: false后配合watch手动处理。

完整类型声明

useUrlSearchParams的完整类型签名如下（对应 useUrlSearchParams.md 中的 Type Declarations 一节）：

export type UrlParams = Record<string, string[] | string> export interface UseUrlSearchParamsOptions<T> extends ConfigurableWindow { /** * @default true */ removeNullishValues?: boolean /** * @default false */ removeFalsyValues?: boolean /** * @default {} */ initialValue?: T /** * Write back to `window.history` automatically * * @default true */ write?: boolean /** * Write mode for `window.history` when `write` is enabled * - `replace`: replace the current history entry * - `push`: push a new history entry * @default 'replace' */ writeMode?: "replace" | "push" /** * Custom function to serialize URL parameters * When provided, this function will be used instead of the default URLSearchParams.toString() * @param params The URLSearchParams object to serialize * @returns The serialized query string (should not include the leading '?' or '#') */ stringify?: (params: URLSearchParams) => string } /** * Reactive URLSearchParams * * @see https://vueuse.org/useUrlSearchParams * @param mode * @param options */ export declare function useUrlSearchParams< T extends Record<string, any> = UrlParams, >( mode?: "history" | "hash" | "hash-params", options?: UseUrlSearchParamsOptions<T>, ): T

几个容易忽视的类型要点：

• 返回值是泛型T（默认UrlParams，即Record<string, string[] | string>），因此可以传入自己的接口类型获得完整的类型提示：

  interface Filters { page: string; keyword: string; tag?: string } const params = useUrlSearchParams<Filters>('history', { initialValue: { page: '1', keyword: '' } }) // params.page / params.keyword 具备类型推断

• 同一个键可以对应字符串数组（string[]），用于表达?tag=a&tag=b这类重复参数；
• 选项接口继承了ConfigurableWindow，意味着可传入自定义的window引用（如 iframe、测试环境模拟对象），这也是它能在 vitest / jsdom 类环境中被可靠测试的接口基础。

三种模式的选型建议

综合上文，给出按路由形态选型的速查：

选型时同时考虑writeMode：筛选、搜索、面板状态这类「中间态」建议保持默认的replace；分页、步骤切换这类「历史可回溯」的状态可切换为push。

在 airi 项目中替换手写解析的落地思路

结合前文列举的真实代码，可以把 airi 中手写的查询串解析统一收拢到useUrlSearchParams：

1. 渲染器启动配置（window-context.ts）：synced-leader、stage-runtime的读取与校验，可改写为带类型参数的useUrlSearchParams<{ 'synced-leader'?: string; 'stage-runtime'?: string }>()，在watch中做合法性校验，同时利用write: false保持启动参数不被误写回；
2. OAuth 回调解析（electron-callback.shared.ts）：回调页属于「一次性读取」场景，原生URLSearchParams依旧高效；若回调页需要把code/state显示在界面上并随用户操作变化，则可切换为useUrlSearchParams('history', { write: false })获得响应式呈现；
3. 悬浮窗调试开关（desktop-overlay-polling.ts）：同时探测 search 与 hash 两处参数的行为，本质是对多模式参数的兼容读取，可封装成一个同时调用useUrlSearchParams('history')与useUrlSearchParams('hash-params')的组合 composable，对外暴露统一的响应式开关。

仓库中还有更多URLSearchParams使用点可作类比参考，例如 weather-api.ts 中构造天气 API 请求串、sign-in.ts 中透传 OIDC 参数、auth-oidc.ts 中编码 token 请求体——这些属于「输出型」编码，通常继续使用原生 API 即可；凡是涉及「读 URL → 驱动 UI → 用户交互 → 写回 URL」闭环的场景，useUrlSearchParams才是更合适的工具。

小结

useUrlSearchParams以最小成本把原生URLSearchParams变成 Vue 3 响应式状态：三种模式覆盖 history 路由、hash 路由与混合形态，removeNullishValues/removeFalsyValues/initialValue提供写入清洗与初始兜底，write/writeMode控制写回策略，stringify允许自定义序列化。结合 airi 仓库中 window-context.ts、electron-callback.shared.ts 与 desktop-overlay-polling.ts 的真实解析逻辑，你可以清晰地判断「何时用手写原生 API、何时交给响应式 composable」，从而在 Vue 3 / Nuxt 3 项目中写出更简洁、更可维护的 URL 状态管理代码。

【免费下载链接】airi💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi