useLocalStorage

معرفی

هوک useLocalStorage مشابه useState عمل می‌کند، اما مقدار را در localStorage ذخیره می‌کند تا بین refresh صفحه و session ها باقی بماند.

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

• ذخیره ترجیحات کاربر (مثلاً حالت نمایش grid/list)
• نگهداری وضعیت فیلترهای جدول بین بازدیدها
• ذخیره draft فرم‌ها

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

• برای داده‌های حساس (رمز عبور، توکن) — از httpOnly cookie استفاده کنید
• برای داده‌های حجیم — localStorage محدودیت ~5MB دارد
• برای state مشترک بین tab ها — از BroadcastChannel یا storage event استفاده کنید

استفاده

import { useLocalStorage } from '@parto-system-design/ui'

function SettingsPanel() {
  const [viewMode, setViewMode] = useLocalStorage<'grid' | 'list'>('view-mode', 'grid')

  return <ViewToggle value={viewMode} onValueChange={setViewMode} />
}

الگوی رایج: ذخیره فیلترهای جدول

function DataTablePage() {
  const [filters, setFilters] = useLocalStorage('table-filters', {
    platform: 'all',
    dateRange: '7d',
    sentiment: 'all',
  })

  return (
    <FilterBar>
      <PeriodSelector
        value={filters.dateRange}
        onValueChange={(v) => setFilters((prev) => ({ ...prev, dateRange: v }))}
      />
    </FilterBar>
  )
}

پارامترها

مقدار بازگشتی

جزئیات فنی

• SSR-safe: در سرور مقدار initialValue برمی‌گرداند
• سریالیزاسیون: از JSON.stringify/parse استفاده می‌کند
• خطاپذیر: اگر localStorage پر باشد یا مرورگر در حالت خصوصی باشد، بدون خطا ادامه می‌دهد
• Setter تابعی: مانند useState، می‌توانید تابع updater ارسال کنید

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

• برای debounce کردن مقدار قبل از ذخیره → useDebounce