docs: useUrlState

NelsonYong · NelsonYong · commit 19c1d7d998b3 · 2025-04-03T17:19:11.000+08:00
diff --git a/docs/.vitepress/config/zh.ts b/docs/.vitepress/config/zh.ts
@@ -135,6 +135,7 @@ export const zh = defineConfig({
         base: '/zh/hooks/', items: [
           ...sidebarGuide(),
           ...siderbarUseRequest(),
+          ...siderbarUseRequestPlugin(),
           ...sidebarHooks()
         ]
       }
diff --git a/docs/demo/useUrlState/demo.vue b/docs/demo/useUrlState/demo.vue
@@ -0,0 +1,28 @@
+<template>
+  <div>
+    <vhp-button @click="() => addCount()">add</vhp-button>
+    <vhp-button style="margin-left: 16px;" @click="() => subCount()">sub</vhp-button>
+    <vhp-button style="margin-left: 16px;" @click="() => addPage()">add-page</vhp-button>
+    <vhp-button style="margin-left: 16px;" @click="() => subPage()">sub-page</vhp-button>
+    <vhp-button style="margin-left: 16px;" @click="() => clear()">
+      clear
+    </vhp-button>
+    <br />
+    <div>count: {{ state.count }}</div>
+    <div>page: {{ state.page }}</div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+  import useUrlState from '@vue-hooks-plus/use-url-state'
+
+  const defaultState = { count: 0, page: 1 }
+  const state = useUrlState(defaultState, {
+    localStorageKey: 'localStorageKey',
+  })
+  const addCount = () => state.value.count++
+  const subCount = () => state.value.count--
+  const addPage = () => state.value.page++
+  const subPage = () => state.value.page--
+  const clear = () => (state.value = Object.assign({}, defaultState))
+</script>
diff --git a/docs/en/hooks/useUrlState.md b/docs/en/hooks/useUrlState.md
@@ -0,0 +1,50 @@
+---
+map:
+  # 映射到docs的路径
+  path: /useUrlState
+---
+
+# useUrlState
+
+A hook that store the state into url query.
+
+## Install
+
+```bash
+npm i @vue-hooks-plus/use-url-state
+```
+
+
+## Code demonstration
+
+<demo src="useUrlState/demo.vue"
+language="vue"
+title="Default usage"
+desc="Store the state into url query. By set the value to undefined, the attribute can be removed from the url query."> </demo>
+
+## API
+
+```typescript
+const state = useUrlState(defaultState, {
+  localStorageKey: 'localStorageKey',
+  routerPushFn,
+})
+
+interface UseUrlStateOptions {
+  localStorageKey?: string
+}
+```
+
+## Params
+
+| Property | Description | Type | Default |
+| --- | --- | --- | --- |
+| initialState | default | `S` \| `() => S` | - |
+| options | When setting `localStorageKey`, if url has no parameter, the value of localStorage is used |
+| UseUrlStateOptions | - |  | routerPushFn | In general, the `router.push` method of passing the vue-router just works | `function` | - |
+
+## Result
+
+| Property | Description      | Type |
+| -------- | ---------------- | ---- |
+| state    | Url query object | -    |
diff --git a/docs/zh/hooks/useUrlState.md b/docs/zh/hooks/useUrlState.md
@@ -0,0 +1,49 @@
+---
+map:
+  # 映射到docs的路径
+  path: /useUrlState
+---
+
+# useUrlState
+
+通过 url query 来管理 state 的 Hook。
+
+## 安装
+
+```bash
+npm i @vue-hooks-plus/use-url-state
+```
+
+## 代码演示
+
+<demo src="useUrlState/demo.vue"
+language="vue"
+title="基本用法"
+desc="将状态同步到 url query 中。通过设置值为 undefind, 可以从 url query 上彻底删除某个属性，从而使用默认值。"> </demo>
+
+## API
+
+```typescript
+const state = useUrlState(defaultState, {
+  localStorageKey: 'localStorageKey',
+  routerPushFn,
+})
+
+interface UseUrlStateOptions {
+  localStorageKey?: string
+}
+```
+
+## Params
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| initialState | 默认值 | `S` \| `() => S` | - |
+| options | 设置`localStorageKey`的话，若 url 没有参数，会使用存在 localStorage 的值 | UseUrlStateOptions | - |
+| routerPushFn | 一般来说，传 vue-router 的 `router.push`方法就行 | `function` | - |
+
+## Result
+
+| 参数  | 说明   | 类型 |
+| ----- | ------ | ---- |
+| state | 状态值 | -    |
diff --git a/package.json b/package.json
@@ -45,6 +45,7 @@
     "@vue-hooks-plus/use-request": "workspace:^2.0.0",
     "@vue-hooks-plus/use-request-plugins": "workspace:^2.0.0",
     "@vue-hooks-plus/use-worker": "workspace:^1.0.0",
+    "@vue-hooks-plus/use-url-state": "workspace:^1.0.0",
     "@vue-hooks-plus/vite-plugin-gen-temp": "^2.6.6",
     "@vue-hooks-plus/vitepress": "^1.2.4",
     "@vue-hooks-plus/vitepress-demo-block": "workspace:^1.0.0",
diff --git a/packages/hooks/package.json b/packages/hooks/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "vue-hooks-plus",
-	"version": "2.3.0-beta.1",
+	"version": "2.3.0-beta.2",
 	"description": "Vue hooks library",
 	"files": [
 		"dist",
@@ -31,8 +31,6 @@
 		"@vue/devtools-api": "^6.5.0",
 		"js-cookie": "^3.0.1",
 		"lodash-es": "^4.17.21",
-		"qs": "^6.11.0",
-		"query-string": "^7.1.1",
 		"screenfull": "^5.0.0"
 	},
 	"peerDependencies": {
diff --git a/packages/hooks/src/index.ts b/packages/hooks/src/index.ts
@@ -45,7 +45,6 @@ import useTimeout from './useTimeout'
 import useTitle from './useTitle'
 import useTrackedEffect from './useTrackedEffect'
 import useUpdate from './useUpdate'
-import useUrlState from './useUrlState'
 import useVirtualList from './useVirtualList'
 import useWhyDidYouUpdate from './useWhyDidYouUpdate'
 import useWinResize from './useWinResize'
@@ -102,7 +101,6 @@ export {
   useTitle,
   useTrackedEffect,
   useUpdate,
-  useUrlState,
   useVirtualList,
   useWhyDidYouUpdate,
   useWinResize,
diff --git a/packages/resolvers/package.json b/packages/resolvers/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@vue-hooks-plus/resolvers",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "",
   "type": "module",
   "main": "dist/index.cjs",
diff --git a/packages/resolvers/src/unplugin-auto-import-resolver/index.ts b/packages/resolvers/src/unplugin-auto-import-resolver/index.ts
@@ -3,6 +3,7 @@ import { resolveModule } from 'local-pkg'
 import { readFileSync } from 'node:fs'
 import VueHooksPlusUseWorkerResolver from './useWorkerResolver'
 import VueHooksPlusUseImmerResolver from './useImmerResolver'
+import VueHooksPlusUseUrlStateResolver from './useUrlStateResolver'
 
 let hooks: string[] | undefined
 
@@ -57,4 +58,4 @@ function VueHooksPlusResolver(options: VueHooksPlusResolverOptions = {}): Resolv
   }
 }
 
-export { VueHooksPlusUseImmerResolver, VueHooksPlusUseWorkerResolver, VueHooksPlusResolver }
+export { VueHooksPlusUseImmerResolver, VueHooksPlusUseWorkerResolver, VueHooksPlusResolver, VueHooksPlusUseUrlStateResolver }
diff --git a/packages/resolvers/src/unplugin-auto-import-resolver/useUrlStateResolver.ts b/packages/resolvers/src/unplugin-auto-import-resolver/useUrlStateResolver.ts
@@ -0,0 +1,49 @@
+import { Resolver } from 'unplugin-auto-import/types'
+let hooks: string[] | undefined
+
+export type VueHooksPlusResolverOptions = {
+  /**
+   * prefix for name of components
+   *
+   * @default ''
+   */
+  prefix?: string
+}
+
+function queryMetaData() {
+  try {
+    hooks = ['useUrlState ']
+  } catch (e) {
+    console.error(e)
+    throw new Error(
+      '[@vue-hooks-plus/use-url-state:plugins] failed to load @vue-hooks-plus/use-url-state, have you installed it?',
+    )
+  }
+}
+
+function resolveHooks(name: string, options: VueHooksPlusResolverOptions) {
+  if (!hooks) return
+
+  const { prefix } = options
+  if (prefix) {
+    if (!name.startsWith(prefix)) return
+    name = name.substring(prefix.length)
+  }
+  if (!hooks.includes(name)) return
+
+  return {
+    name,
+    from: '@vue-hooks-plus/use-url-state',
+  }
+}
+
+export default function VueHooksPlusUseUrlStateResolver(
+  options: VueHooksPlusResolverOptions = {},
+): Resolver {
+  return name => {
+    if (!hooks) {
+      queryMetaData()
+    }
+    return resolveHooks(name, options)
+  }
+}
diff --git a/packages/use-url-state/LICENSE b/packages/use-url-state/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 YongGit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/use-url-state/README.md b/packages/use-url-state/README.md
@@ -0,0 +1,15 @@
+# useImmer
+
+A hook to use [immer](https://github.com/mweststrate/immer) as a Vue hook to manipulate state.
+
+## Install
+
+```bash
+
+npm i @vue-hooks-plus/use-immer
+
+```
+
+> The `hook` is based on `immer` management status, `immer` will be installed to ensure normal work in the project
+
+> Independent installation `@vue-hooks-plus/use-immer`
diff --git a/packages/use-url-state/package.json b/packages/use-url-state/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@vue-hooks-plus/use-url-state",
+  "version": "1.0.0",
+  "description": "Vue management url state",
+	"files": [
+		"dist",
+		"LICENSE",
+		"package.json",
+		"README.md"
+	],
+  "main": "./dist/useUrlState.cjs.js",
+	"module": "./dist/useUrlState.es.js",
+  "types":"./dist/types/index.d.ts" ,
+  "scripts": {
+    "build": "npm run clean && vite build",
+    "clean": "rimraf dist"
+  },
+  "keywords": [],
+  "dependencies": {
+    "vue-hooks-plus": "workspace:*",
+    "qs": "^6.11.0"
+  },
+  "repository": "https://github.com/InhiblabCore/vue-hooks-plus",
+	"homepage": "https://github.com/InhiblabCore/vue-hooks-plus",
+	"author": "NelsonYong",
+	"license": "MIT"
+}
diff --git a/packages/use-url-state/src/index.ts b/packages/use-url-state/src/index.ts
@@ -4,8 +4,9 @@
  */
 import qs from 'qs'
 import { Ref, ref, watch, watchEffect } from 'vue'
-import useLocalStorageState from '../useLocalStorageState'
-import { isFunction } from '../utils'
+import useLocalStorageState from 'vue-hooks-plus/es/useLocalStorageState'
+
+const isFunction = (value: unknown): value is Function => typeof value === 'function'
 
 export interface UseUrlStateOptions {
   localStorageKey?: string
@@ -69,8 +70,8 @@ function useUrlState<S extends UrlState = Partial<UrlState>>(
 
   const state_ = (localStorageKey
     ? useLocalStorageState(localStorageKey, {
-        defaultValue: defaultState,
-      })[0]
+      defaultValue: defaultState,
+    })[0]
     : ref(defaultState)) as Ref<S>
 
   const state = ref<S>() as Ref<S>
diff --git a/packages/use-url-state/tsconfig.json b/packages/use-url-state/tsconfig.json
@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist", //输出文件
+    "lib": ["esnext", "dom"],
+    "baseUrl": "./",
+    "rootDir": "./"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}
diff --git a/packages/use-url-state/vite.config.ts b/packages/use-url-state/vite.config.ts
@@ -0,0 +1,32 @@
+import path from 'path'
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+export default defineConfig({
+  plugins: [
+    dts({
+      include: ['src/**/*.ts'],
+      outputDir: path.resolve(__dirname, 'dist/types'),
+    }),
+  ],
+  build: {
+    minify: true,
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.ts'),
+      name: 'VueHooks_Plus_useUrlState',
+      formats: ['es', 'cjs', 'iife'],
+      fileName: format => {
+        return `useUrlState.${format}.js`
+      },
+    },
+    chunkSizeWarningLimit: 1000,
+    rollupOptions: {
+      external: ['vue'],
+      output: {
+        globals: {
+          vue: 'Vue',
+        },
+      },
+    },
+  },
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -135,6 +135,7 @@ export const zh = defineConfig({`
`135`	`135`	`base: '/zh/hooks/', items: [`
`136`	`136`	`...sidebarGuide(),`
`137`	`137`	`...siderbarUseRequest(),`
	`138`	`+ ...siderbarUseRequestPlugin(),`
`138`	`139`	`...sidebarHooks()`
`139`	`140`	`]`
`140`	`141`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@vue-hooks-plus/resolvers",`
`3`		`- "version": "1.2.5",`
	`3`	`+ "version": "1.3.0",`
`4`	`4`	`"description": "",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"main": "dist/index.cjs",`
Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,7 @@ import { resolveModule } from 'local-pkg'`
`3`	`3`	`import { readFileSync } from 'node:fs'`
`4`	`4`	`import VueHooksPlusUseWorkerResolver from './useWorkerResolver'`
`5`	`5`	`import VueHooksPlusUseImmerResolver from './useImmerResolver'`
	`6`	`+import VueHooksPlusUseUrlStateResolver from './useUrlStateResolver'`
`6`	`7`
`7`	`8`	`let hooks: string[] \| undefined`
`8`	`9`
`@@ -57,4 +58,4 @@ function VueHooksPlusResolver(options: VueHooksPlusResolverOptions = {}): Resolv`
`57`	`58`	`}`
`58`	`59`	`}`
`59`	`60`
`60`		`-export { VueHooksPlusUseImmerResolver, VueHooksPlusUseWorkerResolver, VueHooksPlusResolver }`
	`61`	`+export { VueHooksPlusUseImmerResolver, VueHooksPlusUseWorkerResolver, VueHooksPlusResolver, VueHooksPlusUseUrlStateResolver }`