Components List

Angular Query Builder (クエリビルダー) コンポーネントの概要

Angular Query Builder は、Angular コンポーネントの一部であり、開発者が指定されたデータセットに対して複雑なデータフィルタリングクエリを作成できる機能豊富な UI を提供します。このコンポーネントを使用すると、式のツリーを構築し、エディターと各フィールドのデータタイプによって決定される条件リストを使用して、それらの間に AND/OR 条件を設定できます。式のグループ化やグループ解除、順序の変更は、ドラッグアンドドロップ機能を使用して実行できます。

IgxQueryBuilderComponent コンポーネントは UI を使用して複雑なクエリを作成する方法を提供します。AND/OR 演算子、条件、および値を指定すると、クエリを記述する式ツリーが作成されます。

Angular Query Builder の例

この Angular Query Builder の例を作成して、Angular Query Builder コンポーネントのデフォルト機能を紹介しました。プラスボタンをクリックして、条件、「and」グループ、および「or」グループを追加します。グループ解除または削除するには、サイドバーに移動します。

このサンプルが気に入りましたか? 完全な Ignite UI for Angularツールキットにアクセスして、すばやく独自のアプリの作成を開始します。無料でダウンロードできます。

Ignite UI for Angular Query Builder を使用した作業の開始

Ignite UI for Angular Query Builder コンポーネントを使用した作業を開始するには、Ignite UI for Angular をインストールする必要があります。既存の Angular アプリケーションで、以下のコマンドを入力します。

ng add igniteui-angular
cmd

Ignite UI for Angular については、「はじめに」トピックをご覧ください。

次に、app.module.ts ファイルに IgxQueryBuilderModule をインポートします。

// app.module.ts

import { IgxQueryBuilderModule } from 'igniteui-angular';
// import { IgxQueryBuilderModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    ...
    imports: [..., IgxQueryBuilderModule],
    ...
})
export class AppModule {}
typescript

あるいは、16.0.0 以降、IgxQueryBuilderComponent をスタンドアロンの依存関係としてインポートすることも、IGX_QUERY_BUILDER_DIRECTIVES トークンを使用してコンポーネントとそのすべてのサポートコンポーネントおよびディレクティブをインポートすることもできます。

// home.component.ts

import { IGX_QUERY_BUILDER_DIRECTIVES, FilteringExpressionsTree, FieldType } from 'igniteui-angular';
// import { IGX_QUERY_BUILDER_DIRECTIVES, FilteringExpressionsTree, FieldType } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: `
    <igx-query-builder #queryBuilder
        [entities]="entities"
        [(expressionTree)]="expressionTree"
        (expressionTreeChange)="onExpressionTreeChange()">
    </igx-query-builder>
    `,
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_QUERY_BUILDER_DIRECTIVES]
    /* or imports: [IgxQueryBuilderComponent] */
})
export class HomeComponent {
    public expressionTree: FilteringExpressionsTree;
    public entities: Array<any>;

    public onExpressionTreeChange() {
        ...
    }
}
typescript

Ignite UI for Angular Query Builder モジュールまたはディレクティブをインポートしたので、igx-query-builder コンポーネントの使用を開始できます。

Angular Query Builder の使用

最初に式ツリーが設定されていない場合は、エンティティと、クエリが返すフィールドを選択することから始めます。その後、条件またはサブグループを追加できます。

条件を追加するには、フィールド、フィールドのデータタイプに基づくオペランド、およびオペランドが単項でない場合は値を選択します。In オペランドと Not In オペランドを使用すると、単に値を指定するのではなく、異なるエンティティの条件を含む内部クエリを作成できます。条件が確定すると、条件情報を含むチップが表示されます。チップをクリックまたはホバーすると、チップを変更したり、その直後に別の条件やグループを追加したりできます。

各グループの上にある (AND or OR) ボタンをクリックすると、グループタイプを変更したり、内部の条件をグループ化解除したりするためのオプションを含むメニューが開きます。

すべての条件は特定のエンティティの特定のフィールドに関連しているため、エンティティを変更すると、すべての事前設定された条件とグループがリセットされます。新しいエンティティを選択すると、showEntityChangeDialog 入力プロパティが false に設定されていない限り、確認ダイアログが表示されます。

entities プロパティを、エンティティ名とそのフィールドの配列を記述する配列に設定することで、コンポーネントの使用を開始できます。各フィールドは、名前とデータタイプによって定義されます。フィールドが選択されると、データタイプに基づいて対応するオペランドが自動的に割り当てられます。 Query Builder には expressionTree 入力プロパティがあります。これを使用して、コントロールの初期状態を設定し、ユーザー指定のフィルタリングロジックにアクセスできます。

ngAfterViewInit(): void {
    const innerTree = new FilteringExpressionsTree(FilteringLogic.And, undefined, 'Companies', ['ID']);
    innerTree.filteringOperands.push({
        fieldName: 'Employees',
        condition: IgxNumberFilteringOperand.instance().condition('greaterThan'),
        conditionName: 'greaterThan',
        searchVal: 100
    });
    innerTree.filteringOperands.push({
        fieldName: 'Contact',
        condition: IgxBooleanFilteringOperand.instance().condition('true'),
        conditionName: 'true'
    });

    const tree = new FilteringExpressionsTree(FilteringLogic.And, undefined, 'Orders', ['*']);
    tree.filteringOperands.push({
        fieldName: 'CompanyID',
        condition: IgxStringFilteringOperand.instance().condition('inQuery'),
        conditionName: 'inQuery',
        searchTree: innerTree
    });
    tree.filteringOperands.push({
        fieldName: 'OrderDate',
        condition: IgxDateFilteringOperand.instance().condition('before'),
        conditionName: 'before',
        searchVal: new Date('2024-01-01T00:00:00.000Z')
    });
    tree.filteringOperands.push({
        fieldName: 'ShippedDate',
        condition: IgxDateFilteringOperand.instance().condition('null'),
        conditionName: 'null'
    });

    this.queryBuilder.expressionTree = tree;
}
typescript

expressionTree は、双方向のバインド可能なプロパティです。これは、エンドユーザーが条件を作成、編集、または削除して UI を変更したときに発行される、対応する expressionTreeChange 出力が実装されていることを意味します。通知を受信して変更に対応するために個別にサブスクライブすることもできます。

<igx-query-builder #queryBuilder
    [entities]="entities"
    [(expressionTree)]="expressionTree"
    (expressionTreeChange)="onExpressionTreeChange()">
</igx-query-builder>
html

式のドラッグ

条件チップは、マウスのドラッグアンドドロップまたはキーボードによる並べ替えアプローチを使用して簡単に再配置できます。これらを使用すると、ユーザーはクエリロジックを動的に調整できます。

チップをドラッグしても、その状態や内容は変更されず、位置のみが変更されます。
チップはグループやサブグループにドラッグすることもできます。たとえば、式のグループ化/グループ解除は、式のドラッグ機能によって実行されます。既存の条件をグループ化するには、まず「追加」グループボタンを使用して新しいグループを追加する必要があります。次に、ドラッグすることで、必要な式をそのグループに移動できます。グループを解除するには、すべての条件を現在のグループの外にドラッグします。最後の条件を移動したら、グループは削除されます。

あるクエリツリーのチップを別のクエリツリーにドラッグすることはできません (例: 親から内部へ、またはその逆)。

キーボード操作

キーの組み合わせ

Tab/Shift + Tab - 次の/前のチップ、ドラッグインジケーター、削除ボタン、式の「追加」ボタンに移動します。
下矢印/上矢印 - チップのドラッグインジケーターがフォーカスされている場合、チップを上下に移動できます。
Space/Enter - フォーカスされた式が編集モードに入ります。チップが移動された場合、これにより新しい位置が確認されます。
Esc - チップの並べ替えがキャンセルされ、元の位置に戻ります。

キーボードの並べ替えは、マウスのドラッグアンドドロップと同じ機能を提供します。チップを移動したら、ユーザーは新しい位置を確認するか、並べ替えをキャンセルする必要があります。

テンプレート化

Ignite UI for Angular Query Builder コンポーネントでは、次の定義済み参照名を使用して、コンポーネントのヘッダーと検索値のテンプレートを定義できます。

ヘッダーテンプレート

デフォルトでは、IgxQueryBuilderComponent ヘッダーは表示されません。これを定義するには、IgxQueryBuilderHeaderComponent を igx-query-builder 内に追加する必要があります。

次に、ヘッダータイトルを設定するために title 入力を使用し、igx-query-builder-header 内にコンテンツを渡すことで、クエリビルダーヘッダーをテンプレート化できます。

以下のコードはこれを実行する方法を示します。

<igx-query-builder #queryBuilder [entities]="this.entities">
        <igx-query-builder-header [title]="'Query Builder Template Sample'">  
        </igx-query-builder-header>
</igx-query-builder>
html

検索値

条件の検索値は、igxQueryBuilderSearchValue ディレクティブを使用してテンプレート化でき、igx-query-builder 本体内の <ng-template> に適用されます。

<igx-query-builder #queryBuilder
    [entities]="entities"
    [expressionTree]="expressionTree">
    <ng-template #searchValueTemplate
                igxQueryBuilderSearchValue 
                let-searchValue
                let-selectedField = "selectedField" 
                let-selectedCondition = "selectedCondition"
                let-defaultSearchValueTemplate = "defaultSearchValueTemplate">
        @if (
            selectedField?.field === 'Region' &&
            (selectedCondition === 'equals' || selectedCondition === 'doesNotEqual')
            ){
            <igx-select [placeholder]="'Select region'" [(ngModel)]="searchValue.value">
                <igx-select-item *ngFor="let reg of regionOptions" [value]="reg">
                    {{ reg.text }}
                </igx-select-item>
            </igx-select>
        } 
        @else if (
            selectedField?.field === 'OrderStatus' &&
            (selectedCondition === 'equals' || selectedCondition === 'doesNotEqual')
            ){
            <igx-radio-group>
                <igx-radio class="radio-sample"
                           *ngFor="let stat of statusOptions"
                           value="{{stat.value}}"
                           [(ngModel)]="searchValue.value">
                    {{stat.text}}
                </igx-radio>
            </igx-radio-group>
        }
            @else {  
            <ng-container #defaultTemplate *ngTemplateOutlet="defaultSearchValueTemplate"></ng-container>
        }
    </ng-template>
</igx-query-builder>
html

フォーマッター

条件が編集モードではないときに表示されるチップ内の検索値の外観を変更するには、フィールド配列にフォーマッター関数を設定できます。検索値と選択された条件には、次のように value 引数と rowData 引数を通じてアクセスできます。

this.ordersFields = [
    { field: "CompanyID", dataType: "string" },
    { field: "OrderID", dataType: "number" },
    { field: "EmployeeId", dataType: "number" },
    { field: "OrderDate", dataType: "date" },
    { field: "RequiredDate", dataType: "date" },
    { field: "ShippedDate", dataType: "date" },
    { field: "ShipVia", dataType: "number" },
    { field: "Freight", dataType: "number" },
    { field: "ShipName", dataType: "string" },
    { field: "ShipCity", dataType: "string" },
    { field: "ShipPostalCode", dataType: "string" },
    { field: "ShipCountry", dataType: "string" },
    { field: "Region", dataType: "string", formatter: (value: any, rowData: any) => rowData === 'equals' || rowData === 'doesNotEqual' ? `${value.value}` : value }},
    { field: "OrderStatus", dataType: "number" }
];
ts

デモ

この Angular Query Builder の例は、Angular Query Builder コンポーネントのヘッダーと検索値のテンプレート化とフォーマッター機能を紹介するために作成しました。

スタイル設定

クエリビルダーのスタイル設定は、すべてのテーマ関数とコンポーネントミックスインが存在する index ファイルをインポートする必要があります。

@use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';
scss

クエリビルダーは、background パラメーターを使用して、そのテーマから背景色を取得します。背景を変更するには、カスタムテーマを作成する必要があります。


$custom-query-builder: query-builder-theme(
  $background: #292826,
  ...
);
scss

Query Builder 内には、ボタン、チップ、ドロップダウン、入力など、他のコンポーネントがあるため、それぞれに個別のテーマを作成する必要があります。

$custom-button: button-theme(
  $schema: $dark-material-schema,
  $background: #292826,
  $foreground: #ffcd0f,
  ...
);

$custom-input-group: input-group-theme(
  $focused-secondary-color: #ffcd0f
);

$custom-chip: chip-theme(
  $background: #ffcd0f,
  $text-color: #292826
);

$custom-icon-button: icon-button-theme(
  $background: #ffcd0f,
  $foreground: #292826
);
scss

この例では、リストされたコンポーネントのパラメーターの一部のみを変更しましたが、button-theme、chip-theme、drop-down-theme、input-group-theme テーマは、それぞれのスタイルを制御するためのより多くのパラメーターを提供します。

上記のようにカラーの値をハードコーディングする代わりに、palette および color 関数を使用してカラーに関してより高い柔軟性を実現することができます。使い方の詳細についてはパレットのトピックをご覧ください。

最後に、css-vars ミックスインを使用して新しいコンポーネントテーマを含めます。

@include css-vars($custom-query-builder);

:host {
  ::ng-deep {
    @include css-vars($custom-input-group);
    @include css-vars($custom-chip);
    @include css-vars($custom-icon-button);

    .igx-filter-tree__buttons {
      @include css-vars($custom-button);
    }
  }
}
scss

コンポーネントが Emulated ViewEncapsulation を使用している場合、クエリビルダーコンポーネント内のコンポーネント (ボタン、チップ、ドロップダウンなど) のスタイルを設定するには、::ng-deep を使用してこのカプセル化を解除する必要があります。

デモ

import { NgModule } from "@angular/core";
import { FormsModule } from "@angular/forms";
import { BrowserModule } from "@angular/platform-browser";
import { BrowserAnimationsModule } from "@angular/platform-browser/animations";
import { AppComponent } from "./app.component";
import { IgxQueryBuilderModule } from "igniteui-angular";
import { QueryBuilderStyleComponent } from "./query-builder-style/query-builder-style.component";



@NgModule({
  bootstrap: [AppComponent],
  declarations: [
	AppComponent,
	QueryBuilderStyleComponent
],
  imports: [
	BrowserModule,
	BrowserAnimationsModule,
	FormsModule,
	IgxQueryBuilderModule
],
  providers: [],
  entryComponents: [],
  schemas: []
})
export class AppModule {}
ts

import { Component } from '@angular/core';

@Component({
    selector: 'app-query-builder-style-sample',
    styleUrls: ['./query-builder-style.component.scss'],
    templateUrl: 'query-builder-style.component.html'
})
export class QueryBuilderStyleComponent {
    
    public fields: any[] = [
        { field: 'ID', dataType: 'string' },
        { field: 'CompanyName', dataType: 'string' },
        { field: 'ContactName', dataType: 'string' },
        { field: 'Employees', dataType: 'number' },
        { field: 'ContactTitle', dataType: 'string' },
        { field: 'DateCreated', dataType: 'date' },
        { field: 'TimeCreated', dataType: 'time' },
        { field: 'Address', dataType: 'string' },
        { field: 'City', dataType: 'string' },
        { field: 'Region', dataType: 'string' },
        { field: 'PostalCode', dataType: 'string' },
        { field: 'Phone', dataType: 'string' },
        { field: 'Fax', dataType: 'string' },
        { field: 'Contract', dataType: 'boolean' }
    ];
}
ts

<igx-query-builder #queryBuilder
    [fields]="fields">    
</igx-query-builder>
html

@use '../../variables' as *;

$yellow: #ffcd0f;
$black: #292826;
$muted-yellow: #ffe482;

$custom-query-builder: query-builder-theme(
    $background: $black,
    $header-background: $black,
    $header-foreground: $yellow
);

$custom-button: button-theme(
    $schema: $dark-material-schema,
    $background: $black,
    $foreground: $yellow,
    $hover-foreground: $black,
    $hover-background: $yellow,
    $focus-foreground: $yellow,
    $focus-background: $black,
    $border-color: $yellow
);

$custom-raised-button: button-theme(
    $schema: $dark-material-schema,
    $background: $yellow,
    $foreground: $black,
    $active-background: $muted-yellow,
    $active-foreground: $black,
    $hover-background: $muted-yellow,
    $hover-foreground: $black,
    $border-color: $yellow,
    $active-border-color: $muted-yellow,
    $hover-border-color: $muted-yellow,
    $focus-border-color: $yellow
);

$custom-button-group: button-group-theme(
    $schema: $dark-material-schema,
    $item-background:  $black,
    $item-text-color: $yellow,
    $item-border-color: $yellow,
    $item-selected-background: $yellow,
    $item-hover-background: $yellow,
    $item-selected-hover-background: $yellow
);

$custom-input-group: input-group-theme(
    $schema: $dark-material-schema,
    $idle-text-color: $yellow,
    $focused-text-color: $yellow,
    $filled-text-color: $yellow,
    $idle-bottom-line-color: $muted-yellow,
    $focused-secondary-color: $yellow
);

$custom-chip: chip-theme(
    $schema: $dark-material-schema,
    $background: $yellow,
    $text-color: $black
);

$custom-drop-down: drop-down-theme(
    $schema: $dark-material-schema,
    $background-color: $black,
    $item-text-color: $yellow,
    $hover-item-background: $yellow,
    $hover-item-text-color: $black,
    $focused-item-background: $yellow,
    $focused-item-text-color: $black,
    $selected-item-background: $yellow,
    $selected-item-text-color: $black,
    $selected-focus-item-background: $yellow,
    $selected-focus-item-text-color: $black,
    $selected-hover-item-background: $yellow,
    $selected-hover-item-text-color: $black
);


:host {
    display: block;
    margin: 16px;

    ::ng-deep {
        @include css-vars($custom-drop-down);
        @include css-vars($custom-query-builder);
        @include css-vars($custom-button-group);
        @include css-vars($custom-input-group);
        @include css-vars($custom-chip);
        @include css-vars($custom-drop-down);

        [igxButton] {
            @include css-vars($custom-button);
        }

        [igxButton="raised"] {
            @include css-vars($custom-raised-button);
        }

        igx-query-builder {
            h6 {
                color: $yellow
            }

            .igx-filter-tree__expression-actions igx-icon {
                color: $yellow
            }

            .igx-filter-tree__expression-actions igx-icon:hover {
                color: $muted-yellow
            }

            .igx-filter-tree__expression-actions igx-icon:focus {
                color: $muted-yellow
            }

            .igx-filter-contextual-menu {
                border: 1px solid $yellow
            }

            .igx-filter-contextual-menu__close-btn {
                position: absolute;
                background: $black;
                border-color: $yellow;
                color: $yellow;
            }
        }
    }
}
scss

サンプルは、Change Theme (テーマの変更) で選択したグローバルテーマの影響を受けません。

WYSIWYG App Builder™ と実際の UI コンポーネントを使用して、Angular アプリ開発を効率化することもできます。

API リファレンス

その他のリソース

コミュニティに参加して新しいアイデアをご提案ください。

Angular Query Builder (クエリ ビルダー) コンポーネントの概要