Skip to content

useUrlSearchParams

反应式 URLSearchParams

¥Reactive URLSearchParams

示例

  • foo=bar
  • vueuse=awesome

用法

¥Usage

ts
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`

哈希模式

¥Hash Mode

与 hash 模式路由一起使用时,指定 modehash

¥When using with hash mode route, specify the mode to hash

ts
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 Params

当与历史模式路由一起使用,但想使用哈希作为参数时,指定 modehash-params

¥When using with history mode route, but want to use hash as params, specify the mode to hash-params

ts
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`

自定义 Stringify 函数

¥Custom Stringify Function

你可以使用 stringify 选项提供一个自定义函数来序列化 URL 参数。当你需要对查询字符串进行特殊格式设置时,此功能非常有用。

¥You can provide a custom function to serialize URL parameters using the stringify option. This is useful when you need special formatting for your query string.

js
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`

类型声明

显示类型声明
ts
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

源代码

源代码示例文档

变更日志

6a523 - feat: Add a stringify option for users to provide stringify logic (#4773)