FilterBar

Kurulum

Paket

@bigbang/ui

İçe aktarma

import { FilterBar } from '@bigbang/ui';

Kaynak

FilterBar.tsx

Storybook

FilterBar · Playground

FilterBar, @bigbang/ui paketindedir. Kurulum ve stil dosyaları Button ile aynıdır; ayrıntılar için Button kod sekmesine bakın.

import { useState } from 'react';
import { FilterBar, type FilterField } from '@bigbang/ui';

type Filters = { query: string; status: string | null; category: string[]; mine: boolean };

const empty: Filters = { query: '', status: null, category: [], mine: false };

const fields: ReadonlyArray<FilterField<Filters>> = [
  { key: 'query', label: 'Ara', kind: 'search' },
  { key: 'status', label: 'Durum', kind: 'select', options: [{ value: 'active', label: 'Etkin' }] },
  { key: 'category', label: 'Kategori', kind: 'multi-select', options: [{ value: 'a', label: 'Kategori A' }] },
  { key: 'mine', label: 'Yalnızca benim', kind: 'toggle' },
];

function Page() {
  const [value, setValue] = useState(empty);
  return <FilterBar fields={fields} value={value} onValueChange={setValue} resultCount={12} />;
}

Özellikler

valueZorunlu

Açıklama

Uygulanan filtreler, tipli bir nesne olarak. Durumda ya da URL'de tutup geri verin.

Tür

Record<string, unknown>

onValueChangeZorunlu

Açıklama

Yeni değerin tamamıyla çağrılır: instant kipinde her değişiklikte; batch kipinde Uygula, Temizle ve çip kaldırmada.

Tür

(value: TFilter) => void

fieldsZorunlu

Açıklama

Denetimler, sırayla. key denetimin düzenlediği value özelliğidir. kind: search (string), select (string ya da null), multi-select (string dizisi), toggle (boolean). İlk search alanı arama kutusudur; diğer alanlar dar ekranda "Diğer filtreler" altına girer.

Tür

readonly FilterField<TFilter>[]

apply

Açıklama

instant her değişikliği hemen uygular. batch bir taslak tutar ve Uygula düğmesiyle uygular; düğme yalnızca taslak value'dan farklıysa etkindir.

Tür

'instant' | 'batch'

Varsayılan

'instant'

resultCount

Açıklama

Uygulanan filtreler için sonuç sayısı. Çiplerin yanında gösterilir ve değişmeyi bıraktıktan 500 ms sonra kibarca duyurulur.

Tür

number

loading

Açıklama

Sonuçlar getiriliyor: sayı yer tutucuya döner, kök aria-busy olur, Uygula yükleniyor durumunu gösterir.

Tür

boolean

Varsayılan

false

defaultValue

Açıklama

"Filtreleri temizle" ile dönülen değer. Verilmezse tüm alanlar boşaltılır.

Tür

Record<string, unknown>

label

Açıklama

Arama bölgesini ekran okuyucuya adlandırır. Varsayılan: "Filtreler" ya da "Filters".

Tür

string

className

Açıklama

Yalnızca yerleşim için: dış boşluk ve genişlik.

Tür

string

children

Açıklama

Parçalarla özel yerleşim. Verilmezse çubuk Search, More (diğer alanlarla), Apply, Clear, Applied ve ResultCount parçalarını yerleştirir.

Tür

ReactNode

FilterBar<TFilter> geneldir: value tipinden TFilter çıkarılır ve fields[].key yalnızca TFilter anahtarlarını kabul eder.

Alan tanımı

FilterField<TFilter>: { key, label, kind, options?, placeholder? }. Değer tipi türe göre sabittir:

kind	value[key] tipi	Boş sayılan
search	string	'' ya da yalnızca boşluk
select	string | null	null ya da ''
multi-select	string[]	[]
toggle	boolean	false

Parçalar

Parça	Özellikler
FilterBar.Search	name?: arama alanının key değeri; varsayılan ilk search alanı.
FilterBar.Field	name: çizilecek alanın key değeri.
FilterBar.More	children: ek alanlar. 1024 px altında düğme ve panel, üstünde satırın parçası.
FilterBar.Apply	batch kipinde Uygula ve Sıfırla; instant kipinde hiçbir şey çizmez.
FilterBar.Clear	Yalnızca bir filtre uygulandığında.
FilterBar.Applied	Çipler (Tag).
FilterBar.ResultCount	resultCount tanımlıysa sayı.

Parçalar yalnızca <FilterBar> içinde kullanılır; dışında hata verir. children verirseniz varsayılan yerleşim çizilmez.

Veri öznitelikleri

• data-component="filter-bar", data-apply: kökte.
• data-part: row, meta, field (data-key ve data-kind ile), more, panel, apply, reset, clear, applied, count.

URL eşitleme

Filtreleri adres çubuğuna yazmak ve geri okumak için iki saf yardımcı vardır. Parametre adı alanın key değeridir; çoklu seçim anahtarı yineler, toggle true olur, boş filtreler yazılmaz.

import { filtersToSearchParams, searchParamsToFilters } from '@bigbang/ui';

const params = filtersToSearchParams(value, fields); // status=active&category=a&category=b
const restored = searchParamsToFilters(window.location.search, fields, empty);

searchParamsToFilters bilinmeyen seçenek değerlerini yok sayar; elle değiştirilmiş bir adres filtrelere geçersiz değer sokamaz. Arama metninin URL’de tutulup tutulmayacağı uygulamanın kararıdır; kişisel bilgi içerebilecek aramaları URL’ye yazmayın.