useFilterParams

همگام‌سازی دوطرفه‌ی state یک FilterProvider با URL (query params) — نه برای صفحهٔ فهرست یا داشبوردی که با قالب ساخته می‌شود

معرفی

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

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

نه در صفحه‌ای که با قالب ساخته می‌شود

نمای یک ListPage و DashboardPage (بازه، تب، فیلترها، مرتب‌سازی، چیدمان، شمارهٔ صفحه) اگر باید در نشانی صفحه بماند، با useViewParams می‌رود — نه با این هوک، نه با useSearchParams، نه با history.replaceState. این یک پاسخِ همهٔ صفحه‌های فهرست و داشبورد است (انتخاب قالب صفحه)، و قاعدهٔ ESLint parto/page-template این هوک را در فایلی که یکی از این دو قالب را رندر می‌کند نشان می‌دهد.

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

وضعیت یک پنل فیلتر (FilterPanel) درون محتوای یک CustomPage که باید با لینک به اشتراک گذاشته شود
صفحه‌ای که پیش از قالب‌ها ساخته شده و فیلترهایش از قبل در نشانی صفحه است، تا وقتی به قالب مهاجرت کند

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

صفحهٔ فهرست یا داشبورد — ListPage / DashboardPage با useViewParams (بالا)
فیلترهای موقتی که نباید در URL بمانند — فقط از خودِ FilterProvider استفاده کنید

استفاده

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

// A type (not an interface): the provider's state is a Record<string, unknown>.
type MapFilters = {
  province: string | null
  topic: string | null
}

// Mirrors a filter panel's state in the URL. Rendered once, inside the panel's FilterProvider.
function UrlSync() {
  useFilterParams<MapFilters>({
    serialize: (s) => ({ province: s.province ?? undefined, topic: s.topic ?? undefined }),
    parse: (p) => ({ province: p.get('province'), topic: p.get('topic') }),
  })
  return null
}

;<FilterProvider initialState={{ province: null, topic: null }}>
  <UrlSync />
  {/* FilterPanel و محتوایی که با آن فیلتر می‌شود */}
</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