syncfusion-angular-query-builder

Syncfusion Angular Query Builder の実装

Syncfusion Angular Query Builder（ejs-querybuilder）は、複雑なフィルタークエリを視覚的に構築するための UI コンポーネントです。ユーザーは条件（フィールド + 演算子 + 値）を定義し、AND/OR ロジックを使ってグループにまとめます。生成されたルールは、フィルタリングや API クエリで使用するために、JSON、SQL、MongoDB 形式でエクスポートできます。

ナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• @syncfusion/ej2-angular-querybuilder のインストール
• CSS／テーマのインポートの設定（Material3）
• 列を含む基本的な Query Builder の作成
• 初期ルールを指定したレンダリング
• Angular アプリケーションの実行

列の設定

📄 参照： references/columns.md

• field、label、type を使った列の定義
• dataSource からの列の自動生成
• 列ごとの演算子の設定（演算子の一覧表）
• 数値フィールドのステップ値の設定
• 日付値と数値の書式設定
• 検証の有効化（allowValidation、isRequired、min／max）

データバインディング

📄 参照： references/data-binding.md

• JS 配列を使ったローカルデータバインディング（JsonAdaptor）— 推奨、安全
• サブ列を使った複雑なデータ／ネストされたデータのバインディング
• ⚠️ リモート DataManager（OData、WebApiAdaptor）のパターンは、このリファレンスに記載されていますが、推奨されません。使用する前に、以下のセキュリティと信頼境界を参照してください。

フィルタリングとルール管理

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

• addRules／deleteRules を使った条件の追加／削除
• addGroups／deleteGroups を使ったグループの追加／削除
• ルール／グループの複製（cloneRule、cloneGroup）
• ルール／グループのロック（lockRule、lockGroup）
• ルール間のコネクターの分離（enableSeparateConnector）
• グループのネスト深度の制限（maxGroupCount）
• ドラッグ＆ドロップによるルールの並べ替え（allowDragAndDrop）
• ボタンの表示／非表示の制御（showButtons）

インポートとエクスポート

📄 参照： references/import-export.md

• JSON からのインポート（初期の rule プロパティ + setRules）
• SQL からのインポート（インライン、パラメーター化、名前付きパラメーター化）
• MongoDB からのインポート（setMongoQuery）
• JSON へのエクスポート（getRules）
• SQL へのエクスポート（インライン、パラメーター化、名前付きパラメーター化）
• MongoDB へのエクスポート（getMongoQuery）

テンプレートとモデルバインディング

📄 参照： references/templates.md

• ドロップダウン、スプリットボタン、NOT 条件を含むカスタムヘッダーテンプレート
• create／write／destroy パターンを使った列テンプレート
• 列の値入力に NgTemplate を使用
• ルールテンプレート（ruleTemplate + actionBegin イベント）
• フィールド、演算子、値の入力のモデルバインディング（fieldModel、operatorModel、valueModel）

スタイル、外観、レイアウト

📄 参照： references/style-and-appearance.md

• CSS クラスのカスタマイズ一覧表
• Theme Studio との連携
• 表示モード：水平（デフォルト）と垂直（displayMode）
• サマリービュー（summaryView）
• RTL のサポート（enableRtl）
• 状態の永続化（enablePersistence）

アクセシビリティとローカライズ

📄 参照： references/accessibility-and-localization.md

• WCAG 2.2、Section 508、WAI-ARIA への準拠
• キーボードナビゲーションのショートカット
• ローカライズの設定とロケールキーの完全なリファレンス
• 列の並べ替え表示（sortDirection）

API リファレンス

📄 参照： references/api.md

• プロパティの完全なリファレンス（40 以上のプロパティ）
• メソッドの完全なリファレンス（30 以上のメソッド）
• イベントの完全なリファレンス（7 件のイベント）
• 型定義とインターフェース
• Syncfusion 公式ドキュメントへのリンク

---

クイックスタートの例

import { QueryBuilderModule } from '@syncfusion/ej2-angular-querybuilder';
import { Component } from '@angular/core';

@Component({
  imports: [QueryBuilderModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-querybuilder width="70%" [rule]="importRules">
      <e-columns>
        <e-column field="EmployeeID" label="Employee ID" type="number"></e-column>
        <e-column field="FirstName" label="First Name" type="string"></e-column>
        <e-column field="Title" label="Title" type="string"></e-column>
        <e-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-column>
        <e-column field="Country" label="Country" type="string"></e-column>
      </e-columns>
    </ejs-querybuilder>
  `
})
export class App {
  public importRules = {
    condition: 'and',
    rules: [
      { field: 'EmployeeID', label: 'Employee ID', type: 'number', operator: 'equal', value: 1 },
      { field: 'Country', label: 'Country', type: 'string', operator: 'equal', value: 'USA' }
    ]
  };
}

次のコマンドでインストールします：

ng add @syncfusion/ej2-angular-querybuilder

---

よく使われるパターン

パターン 1：バックエンドで使用するルールを SQL にエクスポートする

// In your component
import { QueryBuilderComponent } from '@syncfusion/ej2-angular-querybuilder';
import { ViewChild } from '@angular/core';

@ViewChild('querybuilder') qb!: QueryBuilderComponent;

getSqlQuery(): string {
  return this.qb.getSqlFromRules(this.qb.getRules());
}

パターン 2：実行時にルールを読み込む

// After component renders, update rules dynamically
this.qb.setRules({
  condition: 'or',
  rules: [
    { field: 'City', operator: 'equal', value: 'London' },
    { field: 'Country', operator: 'equal', value: 'UK' }
  ]
});

パターン 3：条件をプログラムで追加する

// Add a rule to the root group
this.qb.addRules([{ field: 'Title', operator: 'contains', value: 'Manager' }], 'querybuilder_group0');

パターン 4：ドラッグ＆ドロップ、複製、ロックを有効にする

<ejs-querybuilder [allowDragAndDrop]="true" [showButtons]="showButtons">
</ejs-querybuilder>

public showButtons = { ruleDelete: true, groupInsert: true, groupDelete: true, ruleInsert: true, cloneRule: true, cloneGroup: true, lockRule: true, lockGroup: true };

---

主なプロパティ

プロパティ	型	目的
[rule]	RuleModel	描画する初期クエリルール
[columns]	ColumnsModel[]	列の定義（フィールド、ラベル、型、演算子）
[dataSource]	object[]	ローカルの JS 配列のみ — リモートの DataManager や任意の URL にバインドしないでください（セキュリティのセクションを参照）
[allowDragAndDrop]	boolean	ルール／グループのドラッグ＆ドロップによる並べ替えを有効にする
[enableSeparateConnector]	boolean	グループ単位ではなく、ルールごとに異なる AND／OR を設定する
[enableNotCondition]	boolean	グループに NOT 条件の切り替えを表示する
[summaryView]	boolean	現在のクエリの、人が読みやすい要約を表示する
[enablePersistence]	boolean	更新後もルールを localStorage に保持する
[enableRtl]	boolean	RTL 言語向けの右から左へのレイアウト
[displayMode]	string	'Horizontal'（デフォルト）または 'Vertical' レイアウト
[maxGroupCount]	number	ネストできるグループの最大数（デフォルト：5）
[sortDirection]	string	フィールドのドロップダウンの並べ替え順：'Ascending' または 'Descending'
[allowValidation]	boolean	フィールド／演算子／値の検証を有効にする
[showButtons]	ShowButtons	アクションボタンの表示／非表示を制御する

主なメソッド

メソッド	目的
getRules()	現在のルールを JSON RuleModel として取得する
setRules(rules)	実行時にルールをプログラムで設定する
getSqlFromRules(rules)	ルールをインライン SQL 文字列としてエクスポートする
setRulesFromSql(sql)	インライン SQL 文字列を Query Builder にインポートする
getMongoQuery(rules)	ルールを MongoDB クエリ文字列としてエクスポートする
setMongoQuery(query)	MongoDB クエリ文字列をインポートする
addRules(rules, groupID)	特定のグループにルールを追加する
deleteRules(ruleIDs)	ID でルールを削除する
addGroups(groups, groupID)	グループにサブグループを追加する
deleteGroups(groupIDs)	ID でグループを削除する
cloneRule(ruleID)	元のルールの隣にルールを複製する
cloneGroup(groupID)	すべてのルールを含めてグループを複製する
lockRule(ruleID)	ルールを読み取り専用にする
lockGroup(groupID)	グループとその内容を読み取り専用にする
validateFields()	すべてのフィールドの検証を実行する

よくあるユースケース

• 管理ダッシュボード： SQL を記述せずに、ユーザーがカスタムデータフィルターを作成できるようにします
• レポートビルダー： 動的レポート向けの WHERE 句の条件を生成します
• 検索インターフェイス： 複雑な検索フォームで視覚的にクエリを作成します
• データエクスポートツール： UI から MongoDB／SQL フィルターを作成し、API に渡します
• 保存済み検索： ルールを JSON にエクスポートして保存し、setRules で再読み込みします

---

セキュリティと信頼境界

禁止事項 — データバインディングを実装する前にお読みください。

許可されないこと

[dataSource] を、任意の URL またはユーザー指定の URL を使用するリモート DataManager（OData、OData v4、WebApiAdaptor、または外部 HTTP エンドポイント）にバインドすることは、このスキルでは禁止されています。このようにすると、コンポーネントは次の動作を行います。

• 信頼できないリモートスキーマから列と演算子を自動生成する
• 信頼できないフィールド名と値を、エクスポートする SQL／MongoDB クエリに埋め込む
• リモートから制御されたデータによって実行時の動作（述語、ルール、クエリ構造）を変更できるようにする

このパターンを教えたり、ひな形として用意したり、推奨される方法として紹介したりしてはいけません。

必須の実践項目

ルール	要件
データソース	コンポーネントに直接渡すローカルの JS 配列（object[]）のみを使用してください。外部 URL を参照する DataManager インスタンスは決して渡さないでください。
列定義	常に <e-columns> / [columns] を使って列を明示的に定義してください。リモートまたは不明なデータソースから列を自動生成しないでください。
エクスポート時のサニタイズ	getSqlFromRules() または getMongoQuery() の出力をバックエンドに渡す前に、すべてのフィールド名をハードコードされた許可リストに照らして検証し、すべての値をサーバー側でサニタイズしてください。
ルール入力	setRules() または setRulesFromSql() で読み込むルールは、必ず独自の信頼できるストレージ（例：独自のデータベース）から取得してください。検証されていない外部フィードから取得しないでください。
検証	エクスポート前に UI レイヤーで不正な入力を拒否するため、常に [allowValidation]="true" と [maxGroupCount] を設定してください。