vue-query-params

Удобная работа с query-параметрами во Vue 3 с типизацией и реактивностью. Ссылка на npm-пакет - https://www.npmjs.com/package/vue-query-params

Описание

vue-query-params — это легкая библиотека для синхронизации query-параметров URL с реактивными данными во Vue 3. Позволяет легко читать, изменять, валидировать и сбрасывать параметры запроса, не теряя сторонние параметры и сохраняя типизацию.

Возможности

• Реактивная синхронизация query-параметров с состоянием компонента
• Гибкая типизация параметров (string, number, boolean, array, object, date)
• Кастомная сериализация/десериализация
• Валидация и нормализация значений
• Debounce обновлений URL
• Сброс и очистка параметров
• Не затирает чужие параметры в URL
• Простое подключение как плагина

Установка

npm install vue-query-params

или

yarn add vue-query-params

Быстрый старт

import { useQueryParams } from 'vue-query-params'

const config = {
  page: { type: 'number', default: 1 },
  search: { type: 'string', default: '' },
  tags: { type: 'array', default: [] }
}

const { params, update, reset, clear } = useQueryParams(config)

Теперь params.value всегда содержит актуальные значения из URL, а любые изменения автоматически обновляют адресную строку.

Пример использования

<script setup lang="ts">
import { useQueryParams } from 'vue-query-params'

const config = {
  page: { type: 'number', default: 1 },
  search: { type: 'string', default: '' },
  tags: { type: 'array', default: [] }
}

const { params, update, reset, clear } = useQueryParams(config)
</script>

<template>
  <input v-model="params.search" placeholder="Поиск..." />
  <button @click="update({ page: params.page + 1 })">Следующая страница</button>
  <button @click="reset">Сбросить</button>
  <button @click="clear">Очистить параметры</button>
</template>

useQueryParam

Если вам нужно работать только с одним query-параметром, используйте useQueryParam:

import { useQueryParam } from 'vue-query-params'

const page = useQueryParam('page', { type: 'number', default: 1 })

// page.value — реактивное значение параметра "page"

Параметры:

• key — имя параметра в URL
• config — объект конфигурации (аналогичен одному элементу из useQueryParams)

Возвращает:
Реактивное значение параметра (ref).

Типизация

Конфиг строго типизирован:

const config = {
  page: { type: 'number', default: 1, validate: v => v > 0 },
  filter: { type: 'string', default: '' }
} as const

const { params } = useQueryParams(config)
// params.value.page — number
// params.value.filter — string

Опции

useQueryParams(config, options)

Опция	Описание	По умолчанию
debounce	Задержка обновления URL (мс)	0
router	Кастомный экземпляр vue-router	auto
route	Кастомный route (например, для SSR)	auto
immediate	Синхронизировать сразу при инициализации	true
deep	Глубокий watch параметров	true

API

• params — реактивный объект с параметрами
• update(updates) — обновить параметры
• reset() — сбросить к значениям по умолчанию
• clear() — удалить параметры из URL
• destroy() — остановить синхронизацию

Конфиг параметра

{
  type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'date',
  default: any,
  serialize?: (value) => string,
  deserialize?: (value: string) => any,
  validate?: (value) => boolean,
  normalize?: (value) => any,
  required?: boolean
}

Плагин

Можно подключить как плагин для глобальных настроек:

import { createApp } from 'vue'
import { QueryParamsPlugin } from 'vue-query-params'

createApp(App)
  .use(QueryParamsPlugin, { defaults: { debounce: 200 } })
  .mount('#app')

Лицензия

MIT