syncfusion-react-query-builder

Syncfusion React Query Builder の実装

Syncfusion React Query Builder コンポーネントを実装し、カスタマイズするための包括的なガイドです。Query Builder は、複雑なフィルター条件を作成、管理するための強力な UI コンポーネントです。ルールベースのクエリ、複数のデータ型、SQL 生成、幅広いカスタマイズオプションをサポートしています。

コンポーネントの概要

Query Builder コンポーネントは、複雑なフィルタールールを作成、編集するためのグラフィカルなインターフェイスを提供します。構造化された JSON を出力し、SQL、Mongo クエリ、またはデータのフィルタリング用のカスタム述語に変換できます。主な機能は次のとおりです。

• ルール管理： ルールやグループの作成、編集、削除、ネスト
• 複数のデータ型： 文字列、数値、日付、ブール値、カスタム型をサポート
• 演算子のサポート： 16 種類以上の組み込み演算子（equal、contains、between、in など）
• クエリ変換： SQL、Mongo、またはパラメーター化クエリに変換
• カスタマイズ： カスタムテンプレート、テーマ、スタイル設定
• アクセシビリティ： キーボード操作とスクリーンリーダーに対応した WCAG 準拠
• 高度な機能： ドラッグ＆ドロップ、状態の永続化、複製、ロック

ドキュメントとナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• インストールとパッケージのセットアップ
• 基本的なコンポーネントの初期化
• CSS のインポートとテーマ
• 最初の Query Builder の作成
• 列定義の基本
• アプリケーションの実行

列と演算子

📄 参照： references/columns-and-operators.md

• ColumnsModel を使用した列スキーマの定義
• データソースからの列の自動生成
• ラベルとフィールドのマッピング設定
• データ型ごとにサポートされる演算子
• step プロパティと format プロパティの設定
• 列の検証設定

データバインディング

📄 参照： references/data-binding.md

• ローカルのデータ配列のバインド
• DataManager を使用したリモートデータ
• ODataV4Adaptor の統合
• 動的なデータの更新
• Query Builder での DataManager の使用
• データソースの変更への対応

ルールとフィルタリング

📄 参照： references/rules-and-filtering.md

• ルール構造（RuleModel）の理解
• addRules を使用したプログラムによるルールの作成
• addGroups を使用したグループの作成
• ルールとグループの削除
• ネストされたルール階層の管理
• ドラッグ＆ドロップによるルール管理
• ボタンの表示設定

クエリ変換

📄 参照： references/query-conversion.md

• getSqlFromRules によるルールの SQL への変換
• getMongoQuery による Mongo クエリの生成
• パラメーター化 SQL クエリの作成
• 名前付きパラメーターによる SQL 生成
• DataManager 用の述語への変換
• SQL クエリからのルールのインポート
• SQL 変換におけるローカライズへの対応

テンプレートとカスタマイズ

📄 参照： references/templates-and-customization.md

• カスタムヘッダーテンプレートの作成
• テンプレートへのカスタムコンポーネントの挿入
• CSS クラスと cssClass プロパティを使用したスタイル設定
• Theme Studio との統合
• カスタム演算子の定義
• カスタマイズのための actionBegin イベントへの対応

高度な機能

📄 参照： references/advanced-features.md

• 表示モード（水平レイアウトと垂直レイアウト）
• cloneRule/cloneGroup によるルールとグループの複製
• 読み取り専用アクセスのためのルールとグループのロック
• 視覚的な区別のためのコネクターの分離
• グループ操作の制限
• RTL（右から左）への対応
• enablePersistence による状態の永続化
• 並べ替え方向の設定
• サマリービューの表示
• アクセシビリティとキーボード操作

API リファレンス

📄 参照： references/api-reference.md

• 型とデフォルト値を含む、プロパティの完全な一覧
• パラメーターと戻り値の型を含む、すべてのメソッド
• イベントハンドラーとイベント引数
• モデルインターフェイス（RuleModel、ColumnsModel、ShowButtonsModel）
• 戻り値の型定義とデータ構造
• プロパティの使用パターン

クイックスタートの例

import { ColumnsModel, QueryBuilderComponent, RuleModel } from '@syncfusion/ej2-react-querybuilder';
import React from 'react';

function App() {
  const columnData: ColumnsModel[] = [
    { field: 'EmployeeID', label: 'Employee ID', type: 'number' },
    { field: 'FirstName', label: 'First Name', type: 'string' },
    { field: 'Title', label: 'Title', type: 'string' },
    { field: 'HireDate', label: 'Hire Date', type: 'date', format: 'dd/MM/yyyy' },
    { field: 'Country', label: 'Country', type: 'string' }
  ];

  const initialRules: RuleModel = {
    condition: 'and',
    rules: [
      {
        field: 'EmployeeID',
        label: 'Employee ID',
        operator: 'equal',
        type: 'number',
        value: 1001
      }
    ]
  };

  return (
    <QueryBuilderComponent 
      width="100%" 
      columns={columnData} 
      rule={initialRules}
    />
  );
}

export default App;

一般的なパターン

パターン 1：フィルター済みの結果を SQL として取得する

let qryBldrObj: QueryBuilderComponent;

function generateSQL() {
  const sqlQuery = qryBldrObj.getSqlFromRules();
  console.log('Generated SQL:', sqlQuery);
  // Send to backend for execution
}

パターン 2：プログラムでルールを追加する

function addFilter() {
  qryBldrObj.addRules([
    {
      field: 'Country',
      label: 'Country',
      operator: 'equal',
      type: 'string',
      value: 'USA'
    }
  ], 'group0');
}

パターン 3：SQL をルールに戻す

function importFilter(sqlString: string) {
  qryBldrObj.setRulesFromSql(sqlString);
}

パターン 4：サマリービューを表示する

<QueryBuilderComponent 
  columns={columnData}
  summaryView={true}  // Shows query summary at the bottom
/>

主要な Props の早見表

Prop	型	デフォルト値	目的
columns	ColumnsModel[]	-	使用可能なフィールドと演算子を定義します
rule	RuleModel	{}	初期フィルタールール
dataSource	Object[] | DataManager	[]	バインドするデータ
displayMode	'Horizontal' | 'Vertical'	'Horizontal'	レイアウトの向き
allowDragAndDrop	boolean	false	ドラッグ＆ドロップによるルール管理を有効にします
enablePersistence	boolean	false	状態を localStorage に保存します
enableRtl	boolean	false	右から左へのレイアウト
allowValidation	boolean	false	ルール条件を検証します
summaryView	boolean	false	フィルター済みクエリーの概要を表示します
showButtons	ShowButtonsModel	defaults	追加／削除ボタンの表示を制御します
maxGroupCount	number	5	入れ子になったグループの最大深度
readonly	boolean	false	コンポーネントを読み取り専用にします

一般的なユースケース

ユースケース 1：高度な検索フィルター

ユーザーが複数の条件を使って複雑な検索クエリーを作成できるフィルターインターフェイスを作成します。

1. 検索可能なフィールドの列を定義します
2. 空のルールまたはデフォルトのルールで初期化します
3. showButtons を設定してルール管理を有効にします
4. フォーム送信時に SQL を取得します
5. バックエンドでクエリーを実行します

参照： references/rules-and-filtering.md および references/query-conversion.md

ユースケース 2：データ駆動型ダッシュボード

ユーザーが複数の列にわたってデータをフィルターできるダッシュボードを構築します。

1. DataManager をリモートサービスにバインドします
2. データ型に応じて列を設定します
3. UX を向上させるため、ドラッグ＆ドロップを有効にします
4. getPredicate() を使って DataManager をフィルターします
5. フィルター済みの結果を動的に表示します

参照： references/data-binding.md および references/rules-and-filtering.md

ユースケース 3：クエリーテンプレートシステム

ユーザーがフィルターテンプレートを保存して読み込めるようにします。

1. enablePersistence={true} を設定して状態を自動保存します
2. または、getRules() をデータベースに手動で保存します
3. 必要に応じて setRules() でルールを読み込みます
4. 保存したテンプレートをドロップダウンに表示します

参照： references/advanced-features.md

ユースケース 4：レポートビルダー

カスタムテンプレートを使ったレポートフィルター UI を作成します。

1. ブランドに合わせたカスタムヘッダーテンプレートを設計します
2. ドメイン固有のフィルタリングにカスタム演算子を使います
3. allowValidation で検証を有効にします
4. 明確さを高めるために summaryView を表示します
5. レポート実行用の SQL を生成します

参照： references/templates-and-customization.md および references/advanced-features.md

次のステップ

1. はじめに： パッケージをインストールして、最初の Query Builder を作成します
2. 列の定義： ユーザーがフィルターできるフィールドを設定します
3. データのバインド： ローカルまたはリモートのデータソースに接続します
4. UI の構築： ドラッグ＆ドロップに対応したルールとグループを追加します
5. クエリーの生成： ルールを SQL やその他の形式に変換します
6. カスタマイズ： テーマ、テンプレート、アクセシビリティ機能を適用します

---

お困りですか？ 詳しい例や実装パターンについては、上記の各リファレンスファイルをご確認ください。