vue-use-sync-url

测试地址

Introduce

在后台的列表页中，经常需要保存筛选条件和当前页码等数据，并在页面刷新、从详情页返回列表页时，保持之前的筛选条件。此库可以帮助你将筛选值同步到 url 参数，并在页面第一次加载时或浏览器前进后退时将 url 的值同步到你的筛选控件中。

Install

1npm install vue-use-sync-url
2
3OR
4
5yarn add vue-use-sync-url

API

useSyncUrl

属性	描述	类型
configs	配置	SyncUrlConfig
onDecodeSuccess	页面第一次加载或浏览器前进回退, decode 结束会触发的函数，参数为是否由前进回退触发。	(isPopstate: boolean) => void

返回一个函数，可以传入在配置之外的值。例如 syncToUrl({a: "1"})

SyncUrlConfig

属性	描述	类型	默认值
name	显示在 url 上的名称	string	-
encode	将值转换到 url 上的操作，不是 string 类型的会自动转换为 string 类型	() => string | number | boolean | undefined | null | (string | number | boolean | undefined | null)[]	-
decode	将 url 上的值转换到页面上的操作，第一个参数为对应 name 的值，第二个参数为当前 url 上所有的值，第三个参数表示是否由前进回退触发	(value: string | string[], allValues: Record<string, string | string[]>, isPopstate: boolean) => void	-
omitEmptyString	encode 时，值为空字符串 "" 时是否忽略	boolean	true
omitNull	encode 时，值为 null 时是否忽略	boolean	true
omitUndefined	encode 时，值为 undefined 时是否忽略	boolean	true
false

Usage

url 参数的基础知识

在页面第一次加载、执行浏览器前进回退操作时，需要将 url 参数的值转换到当前页面的组件中，在这里我们称其为 decode。在页面中筛选结束点击提交或切换页码时，需要将这些值转换成参数并设置到 url 的参数上，在这里我们称其为 encode。

假设 url 上的参数为 ?a=1&a=2&b=true，来看看获取参数的方法

1const searchParams = new URL(location.href).searchParams;
2
3// ["1", "2"]
4searchParams.getAll("a");
5
6// "1"
7searchParams.get(a);
8
9// ["true"]
10searchParams.getAll(b);
11
12// "true"
13searchParams.get(b);

从上面的结果可以得知，无论什么值最后都会被解析成 string 类型， 如果存在两个名字相同的 key，则会被解析为 string[]。 所以从 url 参数获取到的类型只为 string ｜ string[]。

如何使用

这里使用 element-plus 的组件做例子

1<script setup>
2import { reactive, onMounted } from "vue";
3import useSyncUrl, { toBoolean } from "vue-use-sync-url";
4
5// 筛选控件的组件值
6const values = reactive({
7  keywords: "",
8  status: "",
9  enable: "",
10});
11
12const syncToUrl = useSyncUrl({
13  configs: [
14    {
15      name: "keywords",
16      decode: (value) => {
17        values.keywords = value;
18      },
19      encode: () => values.keywords,
20    },
21    {
22      name: "status",
23      decode: (value) => {
24        values.status = value;
25      },
26      encode: () => values.status,
27    },
28    {
29      name: "enable",
30      decode: (value) => {
31        values.enable = toBoolean(value);
32      },
33      encode: () => values.enable,
34    },
35  ],
36  onDecodeSuccess: (isPopstate) => {
37    //get  data
38    fetch(....)
39  },
40});
41
42const handleSearch = () => {
43  syncToUrl();
44  // 你可以存储到 storage，比如在详情页使用 router.push(`/base${localStorage.getItem("search")}`)
45  localStorage.setItem("search", location.search);
46};
47</script>
48
49<template>
50  <el-input v-model="values.keywords" />
51  <el-select v-model="values.status">
52    <el-option value="success" label="success" />
53    <el-option value="failed" label="failed" />
54  </el-select>
55  <el-select v-model="values.enable">
56    <el-option :value="true" label="true" />
57    <el-option :value="false" label="false" />
58  </el-select>
59  <el-button @click="handleSearch">search</el-button>
60</template>

encode 例子

自定义将组件值转成 url 参数的方法。如果返回空对象 {} 则会被忽略，不会同步到 url。

1// 转换成 name=1
2{
3  name: "name",
4  encode: () => {
5    return "1"
6  }
7}
8
9// 转换成 name=undefined
10{
11  name: "name",
12  omiUndefined: false,
13  encode: () => {
14    return undefined
15  }
16}
17
18// 转换成 a=1&b=2
19{
20  name: "name",
21  encode: () => {
22    return {
23      a: "1",
24      b: "2",
25    }
26  }
27}
28
29// 转换成 a=1&b=2&b=3
30{
31  name: "name",
32  encode: () => {
33    return {
34      a: "1",
35      b: ["2", "3"],
36    }
37  }
38}
39
40// 忽略
41{
42  name: "name",
43  encode: () => {
44    return {}
45  }
46}
47
48// 转换成 a=1
49{
50  name: "name",
51  encode: () => {
52    return {
53      a: "1",
54      b: undefined,
55    }
56  }
57}
58
59// 转换成 a=1&b=undefined
60{
61  name: "name",
62  omitUndefined: false,
63  encode: () => {
64    return {
65      a: "1",
66      b: undefined,
67    }
68  }
69}