syncfusion-blazor-query-builder

Syncfusion Blazor Query Builder の実装

Syncfusion Blazor Query Builder コンポーネントを使用すると、複雑な条件、ネストされたグループ、ルールベースのロジックでデータをフィルタリングするための、動的でカスタマイズ可能なクエリインターフェイスを構築できます。高度な検索 UI、ビジネスルールエンジン、データフィルタリングのワークフローに最適です。

コンポーネントの概要

Query Builder は、フィルタリングロジックを次の要素に整理します。

• ルール： 個々の条件（フィールド = 値）
• グループ： AND／OR ロジックで結合されたルールの集合
• 演算子： 比較の種類（等しい、含む、範囲内など）
• 列： フィルタリング対象となるデータソースのフィールド

主な機能には、プログラムによるルール／グループの管理、イベント処理、ドラッグ＆ドロップ UI、状態の永続化、豊富なカスタマイズオプションがあります。

ナビゲーションガイド

はじめに

📄 参照： references/getting-started.md

• Blazor WebAssembly と Blazor Server のインストールとセットアップ
• NuGet パッケージの構成
• 初期プロジェクトのセットアップ
• 最初の Query Builder の実行

基本的なセットアップと構成

📄 参照： references/basic-setup.md

• Query Builder コンポーネントの作成
• 列とデータ型の定義
• ボタンの表示設定
• デフォルトのルールと初期状態の設定

フィルタリング、ルール、グループ（主な機能）

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

• プログラムによるルールの追加と削除
• グループの作成と管理
• 演算子と条件
• 複雑なネストグループのパターン
• ユーザー操作と検証

データバインディングとフィルタリング結果

📄 参照： references/data-binding.md

• データソースを Query Builder にバインドする
• フィルタリングされたレコードの取得と操作
• 動的なデータ読み込みのパターン
• データセットへのクエリの適用

イベントとコールバック（主な機能）

📄 参照： references/events-and-callbacks.md

• コンポーネントのライフサイクルイベント（Created、Destroyed）
• ルール変更の追跡（RuleChanged、Changed）
• 変更前の検証（OnValueChange）
• イベント駆動型のクエリ更新

カスタマイズとスタイル設定

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

• CSS のカスタマイズとテーマ設定
• カスタム UI のテンプレートサポート
• カスタム演算子の定義
• グループとルールの視覚的なスタイル設定

高度な機能

📄 参照： references/advanced-features.md

• クエリのインポート／エクスポート（JSON、URL パラメーター）
• 状態の永続化とローカルストレージ
• ルールとグループのドラッグ＆ドロップ管理
• グループルールのロック／複製
• 読み取り専用モード
• クエリの並べ替えとフィルタリング

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

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

• 多言語サポート（ローカライズ）
• 右から左（RTL）への表示サポート
• アクセシビリティのベストプラクティス
• キーボードナビゲーション
• スクリーンリーダーのサポート

トラブルシューティング

📄 参照： references/troubleshooting.md

• よくある構成の問題
• イベント処理の問題
• データバインディングのトラブルシューティング
• パフォーマンスの最適化
• テスト方法

クイックスタート

開始するための最小限の例を次に示します。

@using Syncfusion.Blazor.QueryBuilder

<SfQueryBuilder TValue="Order" DataSource="@Orders">
    <QueryBuilderColumns>
        <QueryBuilderColumn Field="OrderID" Label="Order ID" Type="ColumnType.Number"></QueryBuilderColumn>
        <QueryBuilderColumn Field="CustomerName" Label="Customer" Type="ColumnType.String"></QueryBuilderColumn>
        <QueryBuilderColumn Field="OrderDate" Label="Date" Type="ColumnType.Date"></QueryBuilderColumn>
    </QueryBuilderColumns>
</SfQueryBuilder>

@code {
    private List<Order> Orders { get; set; } = new()
    {
        new() { OrderID = 1, CustomerName = "Acme Corp", OrderDate = new(2024, 1, 15) },
        new() { OrderID = 2, CustomerName = "Tech Ltd", OrderDate = new(2024, 2, 20) }
    };

    public class Order {
        public int OrderID { get; set; }
        public string CustomerName { get; set; }
        public DateTime OrderDate { get; set; }
    }
}

よく使われるパターン

プログラムでルールを追加する

<SfButton OnClick="AddFilterRule">Add Rule</SfButton>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    
    private async Task AddFilterRule() {
        var rule = new RuleModel {
            Label = "Order ID",
            Field = "OrderID",
            Type = "Number",
            Operator = "equal",
            Value = 1000
        };
        await QueryBuilder.AddRule(rule, "group0");
    }
}

クエリの変更を取得する

<SfQueryBuilder TValue="Order" DataSource="@Orders">
    <QueryBuilderEvents TValue="Order" RuleChanged="OnRuleChanged"></QueryBuilderEvents>
</SfQueryBuilder>

@code {
    private void OnRuleChanged(RuleChangeEventArgs args) {
        Console.WriteLine($"Query changed: {args.RuleID}");
        // Apply new filter or update results
    }
}

クエリを JSON にエクスポートする

<SfButton OnClick="ExportQuery">Export</SfButton>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    
    private async Task ExportQuery() {
        var queryJson = QueryBuilder.GetRules();
        // Save or transmit queryJson
    }
}

ルールまたはグループを複製する

<SfQueryBuilder TValue="Order" @ref="QueryBuilder">
    <QueryBuilderShowButtons CloneGroup="true" CloneRule="true"></QueryBuilderShowButtons>
</SfQueryBuilder>

<SfButton OnClick="CloneRule">Clone Rule</SfButton>
<SfButton OnClick="CloneGroup">Clone Group</SfButton>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    
    private void CloneRule() {
        // Clone the first rule at position 1
        QueryBuilder.CloneRule("group0_rule0", 1);
    }
    
    private void CloneGroup() {
        // Clone group1 at position 2
        QueryBuilder.CloneGroup("group1", 2);
    }
}

ルールまたはグループをロックする

<SfQueryBuilder TValue="Order" @ref="QueryBuilder">
    <QueryBuilderShowButtons LockGroup="true" LockRule="true"></QueryBuilderShowButtons>
</SfQueryBuilder>

<SfButton OnClick="LockRule">Lock Rule</SfButton>
<SfButton OnClick="UnlockRule">Unlock Rule</SfButton>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    
    private void LockRule() {
        // Lock the rule to prevent editing
        QueryBuilder.LockRule("group0_rule0", true);
    }
    
    private void UnlockRule() {
        // Unlock the rule to allow editing
        QueryBuilder.LockRule("group0_rule0", false);
    }
}

クエリのエクスポート方法

Query Builder には、クエリをさまざまな形式でエクスポートするための組み込みメソッドが用意されています。

1. GetSqlFromRules - インライン SQL としてエクスポート

クエリルールを標準的な SQL WHERE 句の形式に変換します。

<SfQueryBuilder TValue="Order" @ref="QueryBuilder">
    <QueryBuilderColumns>
        <QueryBuilderColumn Field="OrderID" Label="Order ID" Type="ColumnType.Number"></QueryBuilderColumn>
        <QueryBuilderColumn Field="CustomerName" Label="Customer" Type="ColumnType.String"></QueryBuilderColumn>
    </QueryBuilderColumns>
</SfQueryBuilder>

<SfButton OnClick="ExportInlineSQL">Get SQL Query</SfButton>
<p>@SqlQuery</p>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    private string SqlQuery = "";
    
    private void ExportInlineSQL() {
        RuleModel rules = QueryBuilder.GetValidRules();
        SqlQuery = QueryBuilder.GetSqlFromRules(rules);
        // Output: "OrderID = 1000 AND CustomerName LIKE '%Acme%'"
    }
    
    public class Order {
        public int OrderID { get; set; }
        public string CustomerName { get; set; }
    }
}

2. GetParameterSql - パラメーター化 SQL としてエクスポート

SQL インジェクションを防ぐため、インデックス付きパラメーターを含む SQL をエクスポートします。

@using System.Text.Json

<SfButton OnClick="ExportParameterSQL">Get Parameterized SQL</SfButton>
<pre>@ParameterSqlJson</pre>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    private string ParameterSqlJson = "";
    
    private void ExportParameterSQL() {
        RuleModel rules = QueryBuilder.GetValidRules();
        ParameterSql paramSql = QueryBuilder.GetParameterSql(rules);
        
        ParameterSqlJson = JsonSerializer.Serialize(paramSql, new JsonSerializerOptions { 
            WriteIndented = true,
            Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping 
        });
        
        // Access individual properties:
        // paramSql.Sql - SQL string with ? placeholders
        // paramSql.Parameters - List of parameter values
    }
}

出力例：

{
  "Sql": "OrderID = ? AND CustomerName LIKE ?",
  "Parameters": [1000, "%Acme%"]
}

3. GetNamedParameterSql - 名前付きパラメーター SQL としてエクスポート

名前付きパラメーター（@param0、@param1 など）を使用して SQL をエクスポートします。

@using System.Text.Json

<SfButton OnClick="ExportNamedParameterSQL">Get Named Parameter SQL</SfButton>
<pre>@NamedParameterSqlJson</pre>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    private string NamedParameterSqlJson = "";
    
    private void ExportNamedParameterSQL() {
        RuleModel rules = QueryBuilder.GetValidRules();
        NamedParameterSql namedParamSql = QueryBuilder.GetNamedParameterSql(rules);
        
        NamedParameterSqlJson = JsonSerializer.Serialize(namedParamSql, new JsonSerializerOptions { 
            WriteIndented = true,
            Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping 
        });
        
        // Access individual properties:
        // namedParamSql.Sql - SQL string with @param placeholders
        // namedParamSql.Parameters - Dictionary of parameter names/values
    }
}

出力例：

{
  "Sql": "OrderID = @param0 AND CustomerName LIKE @param1",
  "Parameters": {
    "@param0": 1000,
    "@param1": "%Acme%"
  }
}

4. GetMongoQuery - MongoDB クエリとしてエクスポート

クエリルールを MongoDB クエリ形式に変換します。

@using System.Text.Json

<SfButton OnClick="ExportMongoQuery">Get MongoDB Query</SfButton>
<pre>@MongoQueryJson</pre>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    private string MongoQueryJson = "";
    
    private void ExportMongoQuery() {
        RuleModel rules = QueryBuilder.GetValidRules();
        string mongoQuery = QueryBuilder.GetMongoQuery(rules);
        
        // Pretty print the JSON
        JsonDocument jsonDoc = JsonDocument.Parse(mongoQuery);
        MongoQueryJson = JsonSerializer.Serialize(jsonDoc.RootElement, new JsonSerializerOptions {
            WriteIndented = true
        });
    }
}

出力例：

{
  "$and": [
    { "OrderID": { "$eq": 1000 } },
    { "CustomerName": { "$regex": "Acme", "$options": "i" } }
  ]
}

クエリのインポート方法

クエリを Query Builder にインポートすることもできます。

@code {
    // Import from SQL
    private void ImportSQL(string sqlQuery) {
        QueryBuilder.SetRulesFromSql(sqlQuery);
    }
    
    // Import from Parameterized SQL
    private void ImportParameterSQL(ParameterSql paramSql) {
        QueryBuilder.SetParameterSql(paramSql);
    }
    
    // Import from Named Parameter SQL
    private void ImportNamedParameterSQL(NamedParameterSql namedParamSql) {
        QueryBuilder.SetNamedParameterSql(namedParamSql);
    }
    
    // Import from MongoDB Query
    private void ImportMongoQuery(string mongoQuery) {
        QueryBuilder.SetMongoQuery(mongoQuery);
    }
}

クエリのエクスポート／インポートの完全な例

@page "/query-export-demo"
@using Syncfusion.Blazor.QueryBuilder
@using Syncfusion.Blazor.Buttons
@using System.Text.Json

<SfQueryBuilder TValue="Order" @ref="QueryBuilder">
    <QueryBuilderColumns>
        <QueryBuilderColumn Field="OrderID" Label="Order ID" Type="ColumnType.Number"></QueryBuilderColumn>
        <QueryBuilderColumn Field="CustomerName" Label="Customer" Type="ColumnType.String"></QueryBuilderColumn>
        <QueryBuilderColumn Field="OrderDate" Label="Order Date" Type="ColumnType.Date"></QueryBuilderColumn>
        <QueryBuilderColumn Field="Amount" Label="Amount" Type="ColumnType.Number"></QueryBuilderColumn>
    </QueryBuilderColumns>
</SfQueryBuilder>

<div class="button-group">
    <SfButton OnClick="@(() => ExportQuery("SQL"))">Export SQL</SfButton>
    <SfButton OnClick="@(() => ExportQuery("ParameterSQL"))">Export Parameter SQL</SfButton>
    <SfButton OnClick="@(() => ExportQuery("NamedSQL"))">Export Named SQL</SfButton>
    <SfButton OnClick="@(() => ExportQuery("MongoDB"))">Export MongoDB</SfButton>
</div>

<div class="output">
    <h3>@OutputTitle</h3>
    <pre>@OutputQuery</pre>
</div>

@code {
    private SfQueryBuilder<Order> QueryBuilder;
    private string OutputQuery = "";
    private string OutputTitle = "";
    
    private void ExportQuery(string format) {
        RuleModel rules = QueryBuilder.GetValidRules();
        
        switch(format) {
            case "SQL":
                OutputTitle = "Inline SQL Query";
                OutputQuery = QueryBuilder.GetSqlFromRules(rules);
                break;
                
            case "ParameterSQL":
                OutputTitle = "Parameterized SQL Query";
                ParameterSql paramSql = QueryBuilder.GetParameterSql(rules);
                OutputQuery = JsonSerializer.Serialize(paramSql, new JsonSerializerOptions { 
                    WriteIndented = true,
                    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping 
                });
                break;
                
            case "NamedSQL":
                OutputTitle = "Named Parameter SQL Query";
                NamedParameterSql namedSql = QueryBuilder.GetNamedParameterSql(rules);
                OutputQuery = JsonSerializer.Serialize(namedSql, new JsonSerializerOptions { 
                    WriteIndented = true,
                    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping 
                });
                break;
                
            case "MongoDB":
                OutputTitle = "MongoDB Query";
                string mongoQuery = QueryBuilder.GetMongoQuery(rules);
                JsonDocument jsonDoc = JsonDocument.Parse(mongoQuery);
                OutputQuery = JsonSerializer.Serialize(jsonDoc.RootElement, new JsonSerializerOptions {
                    WriteIndented = true
                });
                break;
        }
    }
    
    public class Order {
        public int OrderID { get; set; }
        public string CustomerName { get; set; }
        public DateTime OrderDate { get; set; }
        public decimal Amount { get; set; }
    }
}

主な機能一覧

機能	用途	参照
ドラッグ＆ドロップによるルール操作	条件をインタラクティブに並べ替える	advanced-features.md
グループ／ルールの複製	複雑なクエリ構造を複製する	advanced-features.md
グループ／ルールのロック	特定の条件の編集を防ぐ	advanced-features.md
ネストされたグループ	複雑な複数条件のロジック	filtering-and-rules.md
イベント追跡	クエリの変更に対応する	events-and-callbacks.md
状態の永続化	クエリを保存／復元する	advanced-features.md
ローカライズ	多言語対応	localization-and-accessibility.md
カスタムテンプレート	ブランドに合わせた UI	customization-and-styling.md

次のステップ

1. references/getting-started.md から始めて、環境をセットアップします
2. references/basic-setup.md に従って、コンポーネントを設定します
3. references/filtering-and-rules.md で、コアとなるフィルタリングロジックを確認します
4. references/events-and-callbacks.md で、クエリを処理します
5. 高度なシナリオについては、必要に応じて他のガイドを参照してください