نوار فیلتر (FilterBar)

معرفی

کامپوننت‌های FilterBar مجموعه‌ای ترکیب‌پذیر برای ساخت نوار فیلتر هستند. شامل ردیف فیلترها، ناحیه عملیات، دکمه پاک‌کردن، و نمایش فیلترهای فعال می‌شود.

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

• برای ردیف فیلتری که نوارابزار صفحه نیست: ردیف فیلتر داخل یک کارت یا بخش
• وقتی چنین ردیفی به فیلترهای فعال با قابلیت حذف تکی و پاک‌کردن کامل نیاز دارد

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

• برای جست‌وجو، فیلترها و اقدام‌های یک صفحهٔ فهرست (بالای جدول یا فهرست) — از ListPage استفاده کنید
• برای 5 بُعد فیلتر یا بیشتر، یا صفحهٔ جست‌وجو و کاوش — سایدبار فیلتر: filterPanel قالب ListPage (جای فیلترها)
• برای یک فیلتر تکی — از FilterChip به تنهایی استفاده کنید
• وقتی فیلترها نباید قابل حذف باشند — از ToggleGroup استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، پیش‌نمایش زنده را مشاهده کنید.

استفاده

import {
  ControlSizeProvider,
  FilterBar,
  FilterBarRow,
  FilterBarActions,
  FilterBarClear,
  FilterBarActiveFilters,
  FilterChip,
  Button,
} from '@partodata/ui'

export default function PanelFilters() {
  return (
    // یک اندازه برای کل ردیف، در یک جا؛ کنترل‌ها size و کلاس عرض نمی‌گیرند
    <ControlSizeProvider size="sm" controlWidth="intrinsic">
      <FilterBar>
        <FilterBarRow>
          <Button variant="outline">نوع محتوا</Button>
          <Button variant="outline">پلتفرم</Button>
          <Button variant="outline">بازه زمانی</Button>
          <FilterBarActions>
            <FilterBarClear onClear={() => {}} />
          </FilterBarActions>
        </FilterBarRow>
        <FilterBarActiveFilters>
          <FilterChip label="اینستاگرام" onRemove={() => {}} />
          <FilterChip label="هفته گذشته" onRemove={() => {}} />
        </FilterBarActiveFilters>
      </FilterBar>
    </ControlSizeProvider>
  )
}

FilterBar خودش بستر فیلتر است: کنترل‌های بی size داخلش sm (30 پیکسل) می‌شوند، فیلدها هم، مگر یک Provider بیرونی اندازهٔ دیگری بدهد. عرض را FilterBar تغییر نمی‌دهد؛ برای ردیفی که کش نیاید آن را داخل ControlSizeProvider با controlWidth="intrinsic" بگذارید (مثل نمونهٔ بالا)، نه با size یا کلاس عرض روی تک‌تک کنترل‌ها. FilterBarClear هم اندازه‌اش را از همان ردیف می‌گیرد.

کامپوننت‌ها

• FilterBar — wrapper اصلی با فضای عمودی بین ردیف‌ها
• FilterBarRow — ردیف افقی حاوی دکمه‌های فیلتر
• FilterBarActions — ناحیه عملیات در انتهای ردیف (ms-auto)
• FilterBarClear — دکمه پاک‌کردن تمام فیلترها
• FilterBarActiveFilters — ردیف نمایش فیلترهای فعال (اگر خالی باشد مخفی می‌شود؛ label و emptyText اختیاری). بیرون از FilterBar هم کار می‌کند (در یک کارت)، ولی هرگز بالای نتیجه‌ها کنار یک پنل فیلتر: چیپ‌های سایدبار فیلتر داخل خود سایدبارند (FilterPanelActiveFilters)

Props

FilterBar

FilterBarClear

FilterBarRow / FilterBarActions / FilterBarActiveFilters

همه این کامپوننت‌ها React.HTMLAttributes<HTMLDivElement> را می‌پذیرند و از className پشتیبانی می‌کنند.

حالت‌ها و انواع

با دکمه‌های فیلتر

ردیف دکمه‌ها برای انتخاب نوع فیلتر (نوع محتوا، پلتفرم، بازه زمانی و ...).

با فیلترهای فعال

نمایش فیلترهای اعمال‌شده به صورت FilterChip در ردیف جداگانه.

با دکمه پاک‌کردن

FilterBarClear برای حذف تمام فیلترها به صورت یکجا.

راهنمای استفاده

دسترسی‌پذیری

• FilterBarActiveFilters از aria-label داخلی برای معرفی فیلترهای فعال استفاده می‌کند
• FilterBarClear دارای متن قابل خواندن توسط screen reader است
• تمام دکمه‌ها با صفحه‌کلید قابل دسترسی هستند
• پشتیبانی کامل از RTL

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

• اگر فقط نیاز به نمایش یک فیلتر فعال دارید → FilterChip
• اگر نیاز به انتخاب فیلترها از لیست dropdown دارید → MultiSelect
• اگر نیاز به فیلتر زمانی دارید → DateRangePicker (بازه‌های آماده و بازهٔ دلخواه)