Visão geral do componente Angular Query Builder

    Angular Query Builder faz parte dos nossos Angular Components e fornece uma UI rica que permite aos desenvolvedores criar consultas complexas de filtragem de dados para um conjunto de dados especificado. Com este componente, eles podem criar uma árvore de expressões e definir condições AND/OR entre elas com editores e listas de condições determinadas pelo tipo de dados de cada campo. A árvore de expressão pode então ser facilmente transformada em uma consulta no formato que o backend suporta.

    OIgxQueryBuilderComponent componente oferece uma forma de construir consultas complexas através da interface. Ao especificar operadores, condições e valores AND/OR, o usuário cria uma árvore de expressões que descreve a consulta.

    Angular Query Builder Example

    Criamos este exemplo do Angular Construtor de Consultas para mostrar as funcionalidades padrão do componente Construtor de Consultas do Angular. Clique no botão de adição para adicionar condições, grupo "e", bem como grupo "ou". O agrupamento ou desagrupamento de expressões, bem como a reordenação, podem ser obtidos por meio da funcionalidade Arrastar e soltar.

    Getting Started with Ignite UI for Angular Query Builder

    Para começar a usar o componente Ignite UI for Angular Query Builder, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

    ng add igniteui-angular

    Para obter uma introdução completa ao Ignite UI for Angular, leia o tópico de introdução.

    O próximo passo é importar oIgxQueryBuilderModule arquivo no app.module.ts.

    // app.module.ts

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

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

    Alternativamente,16.0.0 você pode importarIgxQueryBuilderComponent como uma dependência independente ou usar oIGX_QUERY_BUILDER_DIRECTIVES token para importar o componente e todos os seus componentes e diretivas de suporte.

    // home.component.ts

import { IGX_QUERY_BUILDER_DIRECTIVES } from 'igniteui-angular/query-builder';
import { FilteringExpressionsTree, FieldType } from 'igniteui-angular/core';
// 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() {
        ...
    }
}

    Agora que você importou o módulo ou diretivas do Ignite UI for Angular Query Builder, pode começar a usar oigx-query-builder componente.

    Using the Angular Query Builder

    Se nenhuma árvore de expressão for definida inicialmente, você começará escolhendo uma entidade e qual de seus campos a consulta deve retornar. Depois disso, condições ou subgrupos podem ser adicionados.

    Para adicionar uma condição, você seleciona um campo, um operando baseado no tipo de dado do campo e um valor se o operando não for unário. Os operandosIn eNot In permitirão que você crie uma consulta interna com condições para uma entidade diferente em vez de simplesmente fornecer um valor. Uma vez que a condição é comprometida, um chip com a informação da condição aparece. Ao clicar ou passar o mouse no chip, você tem a opção de modificá-lo ou adicionar outra condição ou grupo logo em seguida.

    Clicando no botão (ANDouOR) colocado acima de cada grupo, abrirá um menu com opções para mudar o tipo de grupo ou desagrupar as condições internas.

    Como toda condição está relacionada a um campo específico de uma entidade específica, a mudança da entidade levará ao reset de todas as condições e grupos predefinidos. Ao selecionar uma nova entidade, um diálogo de confirmação será exibido, a menos que ashowEntityChangeDialog propriedade de entrada esteja definida como falsa.

    Você pode começar a usar o componente definindo aentities propriedade para um array que descreve o nome da entidade e um array de seus campos, onde cada campo é definido pelo nome e tipo de dado. Uma vez selecionado um campo, ele automaticamente atribuirá os operandos correspondentes com base no tipo de dado. O Construtor de Consultas tem aexpressionTree propriedade de entrada. Você poderia usá-lo para definir um estado inicial do controle e acessar a lógica de filtragem especificada pelo usuário.

    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;
}

    ÉexpressionTree uma propriedade bindable bidirecional, o que significa que uma saída correspondenteexpressionTreeChange é implementada e emite quando o usuário final altera a interface criando, editando ou removendo condições. Também pode ser assinada separadamente para receber notificações e reagir a tais mudanças.

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

    Expressions Dragging

    Os chips de condição podem ser facilmente reposicionados usando abordagens de arrastar e soltar do mouse ou reordenar o teclado. Com eles, os usuários podem ajustar sua lógica de consulta dinamicamente.

    • Arrastar um chip não modifica sua condição/conteúdo, apenas sua posição.
    • O chip também pode ser arrastado ao longo de grupos e subgrupos. Por exemplo, agrupar/desagrupar expressões é obtido por meio da funcionalidade Arrastar expressões. Para agrupar condições já existentes, primeiro você precisa adicionar um novo grupo através do botão de grupo 'adicionar'. Em seguida, arrastando, as expressões necessárias podem ser movidas para esse grupo. Para desagrupar, você pode arrastar todas as condições para fora do grupo atual e, assim que a última condição for removida, o grupo será excluído.
    Note

    Os chips de uma árvore de consulta não podem ser arrastados para outra, por exemplo, do pai para o interno e vice-versa.

    Exemplo animado de arrastar e soltar com o construtor de consultas usando o mouse

    Keyboard interaction

    Combinações de teclas

    • Tab / Shift + Tab- navega para o chip seguinte/anterior, indicador de arrasto, botão remover, botão de expressão 'adicionar'.
    • Arrow Down / Arrow Up- Quando o indicador de arrasto do chip está focado, o chip pode ser movido para cima/para baixo.
    • Space / Enter- A expressão focalizada entra no modo de edição. Se o chip for movido, isso confirma sua nova posição.
    • Esc- O reordenamento do chip é cancelado e ele retorna à sua posição original.
    Note

    A reordenação do teclado fornece a mesma funcionalidade que o arrastar e soltar do mouse. Depois que um chip é movido, o usuário deve confirmar a nova posição ou cancelar o novo pedido.

    Exemplo animado de arrastar e soltar o teclado usando o Ignite UI for Angular Query Builder

    Templating

    O componente Construtor de consultas do Ignite UI for Angular permite definir modelos para o cabeçalho do componente e o valor de pesquisa usando os seguintes nomes de referência predefinidos:

    Modelo de cabeçalho

    Por padrão, oIgxQueryBuilderComponent cabeçalho não seria exibido. Para definir isso, oIgxQueryBuilderHeaderComponent deve ser adicionado dentro doigx-query-builder.

    Depois, para definir o título do cabeçalho, pode ser usado otitle conteúdo de entrada e passagem dentro doigx-query-builder-header permite com o cabeçalho do construtor de consultas.

    O trecho de código abaixo ilustra como fazer isso:

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

    Search value

    O valor de busca de uma condição pode ser templateado usando aigxQueryBuilderSearchValue diretiva, aplicada ao<ng-template> interior do corpo doigx-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>

    Formatter

    Para alterar a aparência do valor de busca no chip exibido quando uma condição não está em modo de edição, você pode definir uma função de formatador para o array de campos. O valor de busca e a condição selecionada podiam ser acessados através dos argumentos value e rowData da seguinte forma:

    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" }
];

    Demo

    Criamos este exemplo do Construtor de Consultas Angular para mostrar as funcionalidades de modelagem e formatador para o cabeçalho e o valor de pesquisa do componente Construtor de Consultas do Angular.

    Estilização

    Query Builder Theme Property Map

    Quando você modifica uma propriedade primária, todas as propriedades dependentes relacionadas são atualizadas automaticamente para refletir a alteração:

    Propriedade primária Propriedade dependente Descrição
    $background
    		 $label-primeiro plano A cor para as etiquetas do construtor de consultas "de" e "selecionar"
    $header-contextoA cor de fundo do cabeçalho do construtor de consultas
    $header em primeiro planoA cor em primeiro plano do cabeçalho do construtor de consultas
    $subquery-cabeçalho de fundoA cor de fundo do cabeçalho da subquery
    $subquery-cor da bordaA cor da borda do bloco de consulta
    $separator corA cor do separador do bloco de consulta
    $header-borda (apenas Bootstrap)A cor da borda do cabeçalho do construtor de consultas

    Para começar a estilizar o Query Builder, precisamos importar oindex arquivo, onde todas as funções de tema e mixins de componentes estão ativos:

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

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

    O Query Builder pega sua cor de fundo do seu tema, usando obackground parâmetro. Para mudar o fundo, precisamos criar um tema personalizado:

    
$custom-query-builder: query-builder-theme(
  $schema: $dark-material-schema,
  $background: #292826,
  ...
);

    Como temos outros componentes dentro do Query Builder, como botões, chips, menus suspensos e entradas, precisamos criar um tema separado para cada um:

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

$custom-input-group: input-group-theme(
  $schema: $dark-material-schema,
  $focused-secondary-color: #ffcd0f
);

$custom-chip: chip-theme(
  $schema: $dark-material-schema,
  $background: #ffcd0f,
);

$custom-icon-button: outlined-icon-button-theme(
  $schema: $dark-material-schema,
  $foreground: #ffcd0f,
);

    Neste exemplo, mudamos apenas alguns dos parâmetros dos componentes listados, mas osbutton-theme​chip-theme​drop-down-theme​input-group-theme temas fornecem muito mais parâmetros para controlar o estilo respectivo deles.

    Note

    Em vez de codificar os valores de cor como acabamos de fazer, podemos alcançar maior flexibilidade em termos de cores usando aspalette funções e.color Por favor, consulte oPalettes tópico para orientações detalhadas sobre como usá-los.

    O último passo é incluir os novos temas componentes usando ocss-vars mixin.

    @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);
    }
  }
}
    Note

    Se o componente estiver usando umEmulated ViewEncapsulation, é necessário quepenetrate esse encapsulamento use::ng-deep estilizar os componentes dentro do componente do construtor de consultas (botão, chip, menu suspenso ... etc).

    Demo

    Note

    A amostra não será afetada pelo tema global selecionado deChange Theme.

    Styling with Tailwind

    Você pode estilizar o construtor de consultas usando nossas classes utilitárias personalizadas do Tailwind. Certifique-se de configurar o Tailwind primeiro.

    Junto com a importação de vento de cauda em sua folha de estilo global, você pode aplicar os utilitários de tema desejados da seguinte maneira:

    @import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

    O arquivo utilitário inclui tantolight as variantes quantodark as do tema.

    • Uselight-* as aulas para o tema da luz.
    • Usedark-* classes para o tema sombrio.
    • Adicione o nome do componente após o prefixo, por exemplo,light-query-builder,dark-query-builder.

    Uma vez aplicadas, essas classes possibilitam cálculos dinâmicos de temas. A partir daí, você pode sobrescrever as variáveis CSS geradas usandoarbitrary properties. Após os dois-pos, forneça qualquer formato de cor CSS válido (HEX, variável CSS, RGB, etc.).

    Você pode encontrar a lista completa de propriedades no tema de construção de consultas. A sintaxe é a seguinte:

    <igx-query-builder
  class="!light-query-builder ![--background:#90B69F]">
  ...
</igx-query-builder>
    Note

    O ponto de exclamação(!) é necessário para garantir que a classe utilitária tenha prioridade. O Tailwind aplica estilos em camadas e, sem marcar esses estilos como importantes, eles serão substituídos pelo tema padrão do componente.

    No final, seu construtor de consultas deve ficar assim:

    Você também pode otimizar o desenvolvimento do seu aplicativo Angular usando o WYSIWYG App Builder ™ com componentes de interface de usuário reais.

    API References

    Additional Resources

    Nossa comunidade é ativa e sempre acolhedora para novas ideias.