Angular Query Builder 구성 요소 개요

    Angular Query Builder는 Angular Components의 일부이며 개발자가 지정된 데이터 세트에 대한 복잡한 데이터 필터링 쿼리를 빌드할 수 있는 풍부한 UI를 제공합니다. 이 구성 요소를 사용하면 표현식 트리를 빌드하고 각 필드의 데이터 유형에 따라 결정되는 편집기와 조건 목록을 사용하여 표현식 트리 간에 AND/OR 조건을 설정할 수 있습니다. 그런 다음 표현식 트리를 백엔드가 지원하는 형식의 쿼리로 쉽게 변환할 수 있습니다.

    ​IgxQueryBuilderComponent 구성 요소는 UI를 통해 복잡한 쿼리를 작성하는 방법을 제공합니다. AND/OR 연산자, 조건 및 값을 지정하여 사용자는 쿼리를 설명하는 표현식 트리를 만듭니다.

    Angular 쿼리 빌더 예제

    Angular Query Builder 구성 요소의 기본 기능을 보여주기 위해 이 Angular Query Builder 예제를 만들었습니다. 더하기 버튼을 클릭하여 조건, "and" 그룹 및 "or" 그룹을 추가합니다. 표현식을 그룹화하거나 그룹을 해제하고 순서를 변경하는 것은 Drag&Drop 기능을 통해 수행할 수 있습니다.

    EXAMPLE

    이 샘플이 마음에 드시나요? 전체 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에 대한 전체 소개는 시작 항목을 참조하십시오.

    다음 단계는 IgxQueryBuilderModule에서 app.module.ts 파일.

    // 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 가져왔으므로 igx-query-builder 구성 요소를 사용할 수 있습니다.

    Angular 쿼리 빌더 사용

    처음에 표현식 트리가 설정되지 않은 경우 먼저 엔터티와 쿼리가 반환해야 하는 필드를 선택합니다. 그런 다음 조건 또는 하위 그룹을 추가할 수 있습니다.

    조건을 추가하려면 필드, 필드 데이터 유형을 기반으로 하는 피연산자 및 피연산자가 단항이 아닌 경우 값을 선택합니다. 피연산자 In and Not In를 사용하면 단순히 값을 제공하는 대신 다른 엔터티에 대한 조건이있는 내부 쿼리를 만들 수 있습니다. 조건이 커밋되면 상태 정보가 있는 칩이 나타납니다. 칩을 클릭하거나 마우스로 가리키면 칩을 수정하거나 바로 뒤에 다른 조건 또는 그룹을 추가할 수 있는 옵션이 있습니다.

    각 그룹 위에 있는 (AND 또는 OR) 버튼을 클릭하면 그룹 유형을 변경하거나 내부의 조건을 그룹 해제할 수 있는 옵션이 있는 메뉴가 열립니다.

    모든 조건은 특정 엔터티의 특정 필드와 관련되어 있기 때문에 엔터티를 변경하면 미리 설정된 모든 조건 및 그룹이 재설정됩니다. 새 엔터티를 선택할 때 input 속성이 false로 설정되지 않는 한 showEntityChangeDialog 확인 대화 상자가 표시됩니다.

    엔터티 이름과 해당 필드의 배열을 설명하는 배열로 속성을 설정하여 entities 구성 요소를 사용할 수 있으며, 여기서 각 필드는 이름과 데이터 형식으로 정의됩니다. 필드가 선택되면 데이터 유형에 따라 해당 피연산자가 자동으로 할당됩니다. 쿼리 작성기에는 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

    표현식 드래그

    컨디션 칩은 마우스 드래그 앤 드롭 또는 키보드 재정렬 방식을 사용하여 쉽게 재배치할 수 있습니다. 이를 통해 사용자는 쿼리 논리를 동적으로 조정할 수 있습니다.

    • 칩을 드래그하면 상태/내용이 수정되지 않고 위치만 수정됩니다.
    • 칩은 그룹 및 하위 그룹을 따라 드래그할 수도 있습니다. 예를 들어, 표현식 그룹화/그룹 해제는 Expressions Dragging 기능을 통해 수행됩니다. 이미 존재하는 조건을 그룹화하려면 먼저 '추가' 그룹 버튼을 통해 새 그룹을 추가해야 합니다. 그런 다음 드래그를 통해 필요한 표현식을 해당 그룹으로 이동할 수 있습니다. 그룹을 해제하려면 모든 조건을 현재 그룹 외부로 드래그하고 마지막 조건이 이동하면 그룹이 삭제됩니다.

    한 쿼리 트리의 칩은 다른 쿼리 트리에서 드래그 할 수 없습니다 (예 : 부모에서 내부로 또는 그 반대로).

    App Builder | CTA 배너

    키보드 상호 작용

    주요 조합

    • Tab / Shift + Tab- 다음/이전 칩으로 이동하고, 표시기를 드래그하고, 버튼을 제거하고, '추가' 표현식 버튼을 클릭합니다.
    • Arrow Down / Arrow Up- 칩의 드래그 인디케이터에 초점이 맞춰지면 칩을 위/아래로 움직일 수 있습니다.
    • Space / Enter- 초점이 맞춰진 표현식이 편집 모드로 들어갑니다. 칩이 이동되면 새 위치를 확인합니다.
    • Esc- 칩의 재정렬이 취소되고 원래 위치로 돌아갑니다.

    키보드 재정렬은 마우스 드래그 앤 드롭과 동일한 기능을 제공합니다. 칩이 이동되면 사용자는 새 위치를 확인하거나 재주문을 취소해야 합니다.

    템플릿

    Ignite UI for Angular Query Builder 구성 요소를 사용하면 다음과 같은 미리 정의된 참조 이름을 사용하여 구성 요소의 헤더 및 검색 값에 대한 템플릿을 정의할 수 있습니다.

    헤더 템플릿

    기본적으로 헤더는 IgxQueryBuilderComponent 표시되지 않습니다. 이러한 것을 정의하려면 내부에 를 IgxQueryBuilderHeaderComponent 추가해야 합니다. igx-query-builder​

    그런 다음 헤더 제목을 설정하기 위해 사용할 수 있습니다. title input 및 전달 content 내부에서 igx-query-builder-header Query Builder 헤더를 템플릿화할 수 있습니다.

    아래 코드 스니펫은 이 작업을 수행하는 방법을 보여줍니다.

    <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 사용하여 템플릿화할 수 있으며, 본문 내부에 적용됩니다 <ng-template>. igx-query-builder​

    <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

    포맷터

    조건이 편집 모드가 아닐 때 표시되는 칩의 검색 값 모양을 변경하려면 fields 배열에 formatmatter 함수를 설정할 수 있습니다. 검색 값과 선택한 조건은 다음과 같이 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 예제를 만들었습니다.

    EXAMPLE
    TS
    HTML
    SCSS
    Edit in:

    스타일링

    쿼리 빌더 스타일 지정을 시작하려면 모든 테마 기능과 구성 요소 믹스인이 있는 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

    쿼리 빌더 내부에는 버튼, 칩, 드롭다운, 입력과 같은 다른 구성 요소가 있으므로 각 구성 요소에 대해 별도의 테마를 만들어야 합니다.

    $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

    이 예에서는 나열된 구성 요소에 대한 매개 변수 중 일부만 변경했지만 , chip-theme,, drop-down-theme 테마 input-group-theme는 button-theme 해당 스타일을 제어하기 위해 더 많은 매개 변수를 제공합니다.

    우리가 방금 한 것처럼 색상 값을 하드 코딩하는 대신, and color 함수를 사용하여 palette 색상 측면에서 더 큰 유연성을 얻을 수 있습니다. 사용 방법에 대한 자세한 지침은 항목을 참조하십시오 Palettes.

    마지막 단계는 다음과 같습니다. 포함하다를 사용하는 새 구성 요소 테마 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을 사용하려면 다음이 필요합니다. penetrate이 캡슐화는 다음을 사용합니다.::ng-deep Query Builder 구성 요소 내부의 구성 요소를 스타일링하려면 (button, chip, drop-down ... 등).

    데모

    EXAMPLE
    TS
    HTML
    SCSS
    Edit in:

    샘플은 Change Theme에서 선택한 전역 테마의 영향을 받지 않습니다.

    또한 실제 UI 구성 요소와 함께 WYSIWYG App Builder ™사용하여 Angular 앱 개발을 간소화할 수 있습니다.

    API 참조

    추가 리소스

    우리 커뮤니티는 활동적이며 항상 새로운 아이디어를 환영합니다.