メインコンテンツまでスキップ

フィルター検索パネルブロック

FilterSearchPanelコンポーネントは、ReactとTypeScriptで構築された、完全にカスタマイズ可能でアクセシブルなフィルタリング機能付き検索インターフェースです。モダンなデザインパターン、フォームバリデーション、柔軟なカスタマイズオプションを備えた、完全な検索・フィルター体験を提供します。一貫したスタイリングのためにMUIコンポーネント上に構築されています。

🚀 インストール​

npm install @nodeblocks/frontend-filter-search-panel-block@0.3.0

📖 使用方法​

import {FilterSearchPanel} from '@nodeblocks/frontend-filter-search-panel-block';
ライブエディター
function SimpleFilterSearchPanel() {
  const [filters, setFilters] = useState([
    { label: 'アクティブ', key: 'status-active', groupName: 'ステータス' },
    { label: 'ウェブ開発', key: 'category-web', groupName: 'カテゴリー' }
  ]);

  const handleRemoveFilter = (filter) => {
    setFilters(filters.filter(f => f.key !== filter.key));
  };

  const handleSearch = ({search}) => {
    console.log('検索が実行されました:', search);
    setFilters(prev => [...prev, {label: search, key: search, groupName: 'カスタム'}]);
  };

  return (
    <FilterSearchPanel
      filters={filters}
      onClickRemoveFilter={handleRemoveFilter}
      onClickFilterButton={() => console.log('フィルターボタンがクリックされました')}
      onSearch={handleSearch}
      searchPlaceholder="サービスを検索..."
      noFilterText="フィルターが適用されていません"
      filterLabel="フィルター設定"
    >
      <FilterSearchPanel.SearchInput />
      <FilterSearchPanel.ActionGroup />
    </FilterSearchPanel>
  );
}
結果
Loading...

🔧 プロパティリファレンス​

メインコンポーネントのプロパティ​

プロパティ型デフォルト説明
filtersFilterChip[][]表示する現在選択されているフィルターチップの配列
defaultSearchValuestringundefined検索入力フィールドのデフォルト値
onClickRemoveFilter(filter: FilterChip) => voidundefinedフィルターチップが削除されたときにトリガーされるコールバック関数
onClickFilterButton() => voidundefinedフィルターボタンがクリックされたときにトリガーされるコールバック関数
onSearchChange(event: React.ChangeEvent<HTMLInputElement>) => voidundefined検索入力値が変更されたときにトリガーされるコールバック関数
onSearch(data: T) => voidundefined検索データでフォームが送信されたときにトリガーされるコールバック関数
searchPlaceholderstringundefined検索入力フィールドのプレースホルダーテキスト
noFilterTextstringundefinedフィルターが選択されていないときに表示されるテキスト
filterLabelstringundefinedフィルターボタンのラベルテキスト
spacingnumber | string1.5子要素間のスペース（MUI Stackのspacing）
directionStackDirection'column'スタックレイアウトの方向
classNamestringundefinedフォームコンテナのスタイリング用の追加CSSクラス名
sxSxProps<Theme>{ p: 2, bgcolor: 'background.default' }カスタムスタイリング用のMUIシステムプロパティ
childrenBlocksOverrideundefinedデフォルトレンダリングをオーバーライドするカスタムブロックコンポーネント

注意: このコンポーネントはすべてのMUI Stackコンポーネントプロパティ（component="form"としてレンダリング）を継承します。フォーム送信は内部で処理されます - フォームデータを受け取るにはonSearchコールバックを使用してください。

サブコンポーネント​

FilterSearchPanelコンポーネントは複数のサブコンポーネントを提供します。すべてのサブコンポーネントは、メインコンポーネントのコンテキストからデフォルト値を受け取り、プロパティを通じてこれらの値をオーバーライドできます。

FilterSearchPanel.SearchInput​

MUI TextFieldを使用して検索入力フィールドをレンダリングします。

プロパティ型デフォルト説明
searchPlaceholderstring'新規サービス開発'検索入力に表示されるプレースホルダーテキスト
onSearchChange(event: React.ChangeEvent<HTMLInputElement>) => voidコンテキスト値入力値が変更されたときにトリガーされるコールバック関数
defaultSearchValuestringコンテキスト値検索入力のデフォルト値
namestring'search'入力のフォームフィールド名
typestring'text'HTML入力タイプ
childrenReactNodeundefinedカスタムコンテンツ - TextField全体を置き換えます
classNamestringundefinedスタイリング用の追加CSSクラス名
sxSxProps<Theme>undefinedカスタムスタイリング用のMUIシステムプロパティ

注意: このコンポーネントはすべてのMUI TextFieldコンポーネントプロパティを継承します。デフォルトはsize="small"です。フォームを送信する検索アイコンボタンが含まれています。

FilterSearchPanel.FilterButton​

MUI Buttonを使用してフィルター設定ボタンをレンダリングします。

プロパティ型デフォルト説明
filterLabelstring'絞込み設定'フィルターボタンに表示されるラベルテキスト
onClickFilterButton() => voidコンテキスト値ボタンがクリックされたときにトリガーされるコールバック関数
childrenReactNodeデフォルトアイコン+ラベルデフォルトレンダリングをオーバーライドするカスタムコンテンツ
classNamestringundefinedスタイリング用の追加CSSクラス名
sxSxProps<Theme>undefinedカスタムスタイリング用のMUIシステムプロパティ
variantButtonVariant'outlined'MUI Buttonバリアント
sizeButtonSize'small'MUI Buttonサイズ

注意: このコンポーネントはすべてのMUI Buttonコンポーネントプロパティを継承します。デフォルトコンテンツには@mui/icons-materialからのTuneアイコンが含まれています。

FilterSearchPanel.SelectedFilterList​

MUI Boxを使用して選択されたフィルターのリストまたは空の状態をレンダリングします。

プロパティ型デフォルト説明
filtersFilterChip[]コンテキスト値表示するフィルターチップの配列
onClickRemoveFilter(filter: FilterChip) => voidコンテキスト値フィルターが削除されたときにトリガーされるコールバック関数
noFilterTextstring'条件未設定'フィルターが選択されていないときに表示されるテキスト
childrenReactNodeデフォルトフィルターリストデフォルトレンダリングをオーバーライドするカスタムコンテンツ
classNamestringundefinedスタイリング用の追加CSSクラス名
sxSxProps<Theme>undefinedカスタムスタイリング用のMUIシステムプロパティ

注意: このコンポーネントはすべてのMUI Boxコンポーネントプロパティを継承します。groupNameプロパティでフィルターをグループ化し、グループラベルを表示します。

FilterSearchPanel.FilterBadge​

MUI Chipを使用して個別のフィルターチップをレンダリングします。

プロパティ型デフォルト説明
filterFilterChip必須ラベル、キー、オプションのgroupNameを含むフィルターチップオブジェクト
onClickRemoveFilter(filter: FilterChip) => voidコンテキスト値フィルターが削除されたときにトリガーされるコールバック関数
childrenReactNodefilter.labelラベルテキストをオーバーライドするカスタムコンテンツ
classNamestringundefinedスタイリング用の追加CSSクラス名
sxSxProps<Theme>undefinedカスタムスタイリング用のMUIシステムプロパティ

注意: このコンポーネントはすべてのMUI Chipコンポーネントプロパティを継承します。削除用のカスタム閉じるアイコンが含まれています。

FilterSearchPanel.ActionGroup​

MUI Stackを使用してFilterButtonとSelectedFilterListを水平レイアウトで組み合わせます。

プロパティ型デフォルト説明
filtersFilterChip[]コンテキスト値フィルターチップの配列（SelectedFilterListに渡されます）
onClickRemoveFilter(filter: FilterChip) => voidコンテキスト値フィルター削除のコールバック
filterLabelstringコンテキスト値フィルターボタンのラベル
noFilterTextstringコンテキスト値フィルターがないときのテキスト
onClickFilterButton() => voidコンテキスト値フィルターボタンクリックのコールバック
childrenReactNodeデフォルトレイアウトデフォルトレンダリングをオーバーライドするカスタムコンテンツ
classNamestringundefinedスタイリング用の追加CSSクラス名
sxSxProps<Theme>undefinedカスタムスタイリング用のMUIシステムプロパティ

注意: このコンポーネントはすべてのMUI Stackコンポーネントプロパティを継承します。デフォルトはdirection="row"とspacing={1}です。オーバーフロー処理のために非表示スクロールバー付きの水平スクロールが有効になっています。

🎨 設定例​

カスタム検索入力スタイリング​

<FilterSearchPanel.SearchInput 
  sx={{ 
    '& .MuiOutlinedInput-root': {
      bgcolor: 'background.paper',
      borderRadius: 2
    }
  }}
  placeholder="カスタムプレースホルダー..."
/>

カスタムフィルターボタンスタイリング​

<FilterSearchPanel.FilterButton 
  variant="contained"
  color="primary"
  sx={{ minWidth: 150 }}>
  🎯 カスタムフィルター
</FilterSearchPanel.FilterButton>

カスタムアクショングループレイアウト​

<FilterSearchPanel.ActionGroup 
  direction="column"
  spacing={2}
  sx={{ alignItems: 'stretch' }}
/>

🔧 TypeScript サポート​

包括的な型定義による完全なTypeScriptサポート:

import FilterSearchPanel from '@nodeblocks/frontend-filter-search-panel-block';
import {StackProps, TextFieldProps, ButtonProps, ChipProps, BoxProps} from '@mui/material';

// フィルターチップの構造
interface FilterChip {
  label: string;
  key: string;
  groupName?: string;
}

// デフォルトの検索フォームデータ構造
interface SearchFormData {
  search: string;
}

// メインコンポーネントプロパティはMUI StackProps（formとしてレンダリング）を拡張
interface FilterSearchPanelProps<T extends SearchFormData> 
  extends Omit<StackProps<'form'>, 'children' | 'component' | 'onSubmit'> {
  filters?: FilterChip[];
  defaultSearchValue?: string;
  onSearchChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
  onClickFilterButton?: () => void;
  onClickRemoveFilter?: (filter: FilterChip) => void;
  onSearch?: (data: T) => void;
  searchPlaceholder?: string;
  noFilterText?: string;
  filterLabel?: string;
  children?: BlocksOverride;
}

function TypedFilterSearchPanel() {
  const [selectedFilters, setSelectedFilters] = useState<FilterChip[]>([
    {label: 'アクティブ', key: 'status-active', groupName: 'ステータス'},
    {label: 'プレミアム', key: 'type-premium', groupName: 'タイプ'},
  ]);

  const handleSearch = (formData: SearchFormData) => {
    console.log('検索が実行されました:', formData);
  };

  const handleRemoveFilter = (filter: FilterChip) => {
    setSelectedFilters(prev => prev.filter(f => f.key !== filter.key));
  };

  return (
    <FilterSearchPanel
      filters={selectedFilters}
      onSearch={handleSearch}
      onClickRemoveFilter={handleRemoveFilter}
      onClickFilterButton={() => console.log('フィルターモーダルを開いています')}
      searchPlaceholder="サービスを検索..."
      noFilterText="フィルターが適用されていません"
      filterLabel="フィルターオプション"
      spacing={2}
      sx={{maxWidth: 600}}
    >
      <FilterSearchPanel.SearchInput sx={{bgcolor: 'background.paper'}} />
      <FilterSearchPanel.ActionGroup />
    </FilterSearchPanel>
  );
}

📝 注意事項​

  • コンポーネントはデフォルトでspacing={1.5}とdirection="column"のMUI Stackをform要素としてレンダリングします
  • デフォルト背景はbgcolor: 'background.default'とp: 2のパディングです
  • フォーム送信は内部で処理されます - onSearchコールバックはパースされたフォームデータを受け取ります
  • SearchInputにはフォームを送信する検索アイコンボタンが含まれています
  • FilterButtonは@mui/icons-materialからのMUI Tuneアイコンを使用します
  • SelectedFilterListはgroupNameプロパティでフィルターをグループ化し、グループラベルを表示します
  • FilterBadgeにはラベルの前に配置されたカスタム閉じるアイコンが含まれています
  • ActionGroupにはオーバーフロー処理のための非表示スクロールバー付き水平スクロールがあります
  • すべてのサブコンポーネントはMUIシステムスタイリング用のsxプロパティをサポートします
  • ブロックオーバーライドパターンにより、デフォルトブロック間にカスタムブロックを挿入できます

React、TypeScript、MUIを使用して❤️で構築されました。