vue-route-query-hook:一个用于 Vue 3 的 Composable,提供响应式参数与 URL 查询参数之间的双向同步功能

vue-route-query-hook

一个用于 Vue 3 的 Composable,提供响应式参数与 URL 查询参数之间的双向同步功能。

特性

  • 🔄 双向同步: 响应式参数与 URL 查询参数自动同步
  • 🎯 类型安全: 完整的 TypeScript 支持
  • ⚙️ 灵活配置: 支持排除字段、空值处理等多种配置
  • 🚀 Vue 3: 基于 Vue 3 Composition API
  • 📦 轻量级: 无额外依赖,仅依赖 Vue 和 Vue Router

安装

bash 复制代码
npm install vue-route-query-hook

或使用 yarn:

bash 复制代码
yarn add vue-route-query-hook

或使用 pnpm:

bash 复制代码
pnpm add vue-route-query-hook

基础用法

vue 复制代码
<template>
  <div>
    <input v-model="searchParams.keyword" placeholder="搜索关键词" />
    <select v-model="searchParams.status">
      <option value="">全部</option>
      <option value="active">激活</option>
      <option value="inactive">未激活</option>
    </select>
    <input v-model.number="searchParams.page" type="number" min="1" />

    <button @click="resetParams()">重置</button>
  </div>
</template>

<script setup lang="ts">
import { reactive, toRef } from "vue";
import { useRouteQuery } from "vue-route-query-hook";

const searchParams = reactive({
  keyword: "",
  status: "",
  page: 1,
});

const { updateRouteQuery, resetParams } = useRouteQuery({
  q: toRef(searchParams, "keyword"),
  status: toRef(searchParams, "status"),
  page: toRef(searchParams, "page"),
});
</script>

API

useRouteQuery(params, options?)

参数
  • params : QueryParams - 要同步的响应式参数对象

    • key: 路由参数名
    • value: Vue 响应式引用 (Ref)
  • options : UseRouteQueryOptions (可选) - 配置选项

返回值

返回一个包含以下方法的对象:

  • updateRouteQuery : () => void - 手动更新路由查询参数
  • initParamsFromRoute : () => void - 从路由初始化参数
  • resetParams : (resetValues?) => void - 重置参数为初始值

配置选项

UseRouteQueryOptions

typescript 复制代码
interface UseRouteQueryOptions {
  /**
   * 排除的字段,这些字段不会同步到路由
   * @default []
   */
  excludeKeys?: string[];

  /**
   * 是否立即执行 watch 监听
   * @default true
   */
  immediate?: boolean;

  /**
   * 是否在组件挂载时从路由初始化参数
   * @default true
   */
  initFromRoute?: boolean;

  /**
   * 空值处理方式
   * - 'remove': 移除参数
   * - 'keep': 保留参数
   * @default 'remove'
   */
  emptyValueHandle?: "remove" | "keep";
}

高级用法

排除某些字段

typescript 复制代码
const searchParams = reactive({
  keyword: "",
  internalFlag: false, // 这个字段不需要同步到 URL
});

useRouteQuery(
  {
    q: toRef(searchParams, "keyword"),
    internal: toRef(searchParams, "internalFlag"),
  },
  {
    excludeKeys: ["internal"], // 排除 internal 字段
  }
);

手动控制同步时机

typescript 复制代码
const { updateRouteQuery } = useRouteQuery(
  {
    status: toRef(searchParams, "status"),
  },
  {
    immediate: false, // 禁用自动同步
  }
);

// 在需要的时候手动同步
function handleSubmit() {
  updateRouteQuery();
}

保留空值参数

typescript 复制代码
useRouteQuery(
  {
    q: toRef(searchParams, "keyword"),
  },
  {
    emptyValueHandle: "keep", // 空值时保留参数为空字符串
  }
);

自定义重置值

typescript 复制代码
const { resetParams } = useRouteQuery({
  keyword: toRef(searchParams, "keyword"),
  page: toRef(searchParams, "page"),
});

// 重置为默认值
resetParams();

// 重置为指定值
resetParams({
  keyword: "default search",
  page: 1,
});

类型支持

该包提供完整的 TypeScript 类型支持:

typescript 复制代码
import type {
  QueryValue,
  QueryParams,
  UseRouteQueryOptions,
  UseRouteQueryReturn,
} from "vue-route-query-hook";

类型定义

typescript 复制代码
type QueryValue = string | number | boolean | undefined | null;
type QueryParams = Record<string, Ref<QueryValue>>;

注意事项

  1. 类型转换: Hook 会根据原始值的类型自动转换路由参数

    • number: 转换为数字,无效时保持原值
    • boolean: 'true' 转换为 true,其他为 false
    • string: 直接返回字符串值
  2. 历史记录 : 使用 router.replace 更新路由,不会产生浏览器历史记录

  3. 深度监听: 自动开启深度监听,支持嵌套对象的变化检测

兼容性

  • Vue 3.0+
  • Vue Router 4.0+

仓库地址

许可证

MIT

作者

高顺鹏 handsome@gaoshunpeng.cn

相关推荐
胡gh4 小时前
页面卡成PPT?重排重绘惹的祸!依旧性能优化
前端·javascript·面试
胡gh4 小时前
简单又复杂,难道只能说一个有箭头一个没箭头?这种问题该怎么回答?
javascript·后端·面试
言兴4 小时前
# 深度解析 ECharts:从零到一构建企业级数据可视化看板
前端·javascript·面试
山有木兮木有枝_4 小时前
TailWind CSS
前端·css·postcss
烛阴5 小时前
TypeScript 的“读心术”:让类型在代码中“流动”起来
前端·javascript·typescript
杨荧5 小时前
基于Python的农作物病虫害防治网站 Python+Django+Vue.js
大数据·前端·vue.js·爬虫·python
Moment6 小时前
毕业一年了,分享一下我的四个开源项目!😊😊😊
前端·后端·开源
程序视点7 小时前
Escrcpy 3.0投屏控制软件使用教程:无线/有线连接+虚拟显示功能详解
前端·后端
silent_missile7 小时前
element-plus穿梭框transfer的调整
前端·javascript·vue.js
专注VB编程开发20年7 小时前
OpenXml、NPOI、EPPlus、Spire.Office组件对EXCEL ole对象附件的支持
前端·.net·excel·spire.office·npoi·openxml·spire.excel