useFilterParams

همگام‌سازی دوطرفه‌ی state یک FilterProvider با URL (query params)

معرفی

هوک useFilterParams وضعیتِ یک <FilterProvider> را دوطرفه با URLSearchParams همگام می‌کند: روی mount از URL می‌خواند و با هر تغییرِ فیلتر (با debounce ۲۰۰ms) آن را در URL می‌نویسد. اعدادِ فارسی/عربیِ ورودی به لاتین نرمال می‌شوند و کل هوک SSR-safe است.

باید درونِ <FilterProvider> استفاده شود — وگرنه خطا می‌دهد تا اشتباهِ wiring زود معلوم شود.

چه زمانی استفاده کنیم

اشتراک‌گذاری یا bookmark کردنِ یک نمای فیلترشده با لینک
حفظِ فیلترها هنگام refresh یا دکمه‌ی back/forward مرورگر

چه زمانی استفاده نکنیم

فیلترهای موقتی که نباید در URL بمانند — فقط از خودِ FilterProvider استفاده کنید

استفاده

import { FilterProvider, useFilterParams } from '@partodata/ui'

function FilteredList() {
  useFilterParams({
    serialize: (s) => ({
      q: s.q || undefined,
      page: s.page > 1 ? String(s.page) : undefined,
    }),
    parse: (p) => ({ q: p.get('q') ?? '', page: Number(p.get('page') ?? '1') }),
  })
  // … رندرِ لیست بر اساس state فیلتر
  return null
}

;<FilterProvider initialState={{ q: '', page: 1 }}>
  <FilteredList />
</FilterProvider>

پارامترها (options)

فیلد	نوع	پیش‌فرض	توضیح
`serialize`	`(state) => Record<string, string \| undefined \| null>`	—	state → پارامترهای URL؛ مقادیرِ `undefined`/`null` حذف می‌شوند
`parse`	`(params: URLSearchParams) => Partial<state>`	—	URL → بخشی از state (روی mount و back/forward)
`debounceMs`	`number`	`200`	تأخیر پیش از نوشتن در URL
`history`	`'push' \| 'replace'`	`'replace'`	`replace` دکمه‌ی back را برای ناوبریِ واقعی مفید نگه می‌دارد
`disabled`	`boolean`	`false`	غیرفعال‌سازیِ موقت (مثلاً تا آماده‌شدنِ داده‌ی سمتِ سرور)

بازگشتی: void.

هوک‌های مرتبط

ذخیره‌ی فیلترها به‌صورت preset نام‌دار → useFilterPresets