Descripción general del componente Angular Query Builder

    Angular Query Builder es parte de nuestros componentes Angular y proporciona una interfaz de usuario completa que permite a los desarrolladores crear consultas de filtrado de datos complejas para un conjunto de datos específico. Con este componente, pueden crear un árbol de expresiones y establecer condiciones AND/OR entre ellas con editores y listas de condiciones determinadas por el tipo de datos de cada campo. El árbol de expresiones se puede transformar fácilmente en una consulta en el formato que admita el backend.

    El componente IgxQueryBuilderComponent proporciona una forma de crear consultas complejas a través de la interfaz de usuario. Al especificar operadores, condiciones y valores Y/O, el usuario crea un árbol de expresión que describe la consulta.

    Ejemplo de generador de consultas Angular

    Hemos creado este ejemplo de Angular Query Builder para mostrarle las funcionalidades predeterminadas del componente Angular Query Builder. Haga clic en el botón más para agregar condiciones, el grupo "y" y el grupo "o". La agrupación o desagrupación de expresiones, así como el reordenamiento, se pueden lograr a través de la funcionalidad de arrastrar y soltar.

    EXAMPLE

    ¿Te gusta esta muestra? Obtenga acceso a nuestro kit de herramientas de Ignite UI for Angular completo y comience a crear sus propias aplicaciones en minutos. Descárgalo gratis.

    Introducción a Ignite UI for Angular Generador de consultas

    Para empezar a utilizar el componente Ignite UI for Angular Query Builder, primero debe instalar Ignite UI for Angular. En una aplicación Angular existente, escriba el siguiente comando:

    ng add igniteui-angular
cmd

    Para obtener una introducción completa al Ignite UI for Angular, lea el tema de introducción.

    El siguiente paso es importar IgxQueryBuilderModule en el archivo 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

    Alternativamente, a partir de 16.0.0, puede importar IgxQueryBuilderComponent como una dependencia independiente o usar el token IGX_QUERY_BUILDER_DIRECTIVES para importar el componente y todos sus componentes y directivas de soporte.

    // 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

    Ahora que ha importado el módulo o las directivas de Ignite UI for Angular Query Builder, puede empezar a utilizar el igx-query-builder componente.

    Uso del generador de consultas Angular

    Si no se establece inicialmente ningún árbol de expresión, comience eligiendo una entidad y cuáles de sus campos debe devolver la consulta. Después de eso, se pueden agregar condiciones o subgrupos.

    Para añadir una condición, seleccione un campo, un operando basado en el tipo de datos del campo y un valor si el operando no es unario. Los operandos In y Not In le permitirán crear una consulta interna con condiciones para una entidad diferente en lugar de simplemente proporcionar un valor. Una vez confirmada la condición, aparece un chip con la información de la condición. Al hacer clic o pasar el cursor sobre el chip, tiene las opciones para modificarlo o agregar otra condición o grupo justo después de él.

    Al hacer clic en el botón (AND o OR) situado encima de cada grupo, se abrirá un menú con opciones para cambiar el tipo de grupo o desagrupar las condiciones que contienen.

    Dado que cada condición está relacionada con un campo específico de una entidad en particular, cambiar la entidad conducirá al restablecimiento de todas las condiciones y grupos preestablecidos. Al seleccionar una nueva entidad, se mostrará un cuadro de diálogo de confirmación, a menos que la propiedad de showEntityChangeDialog entrada se establezca en false.

    Puede empezar a utilizar el componente estableciendo la entities propiedad en una matriz que describa el nombre de la entidad y una matriz de sus campos, donde cada campo se define por su nombre y tipo de datos. Una vez que se selecciona un campo, se asignarán automáticamente los operandos correspondientes en función del tipo de datos. El Generador de consultas tiene la expressionTree propiedad input. Puede usarlo para establecer un estado inicial del control y tener acceso a la lógica de filtrado especificada por el usuario.

    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

    Es expressionTree una propiedad enlazable bidireccional, lo que significa que se implementa una salida correspondiente expressionTreeChange que se emite cuando el usuario final cambia la interfaz de usuario creando, editando o quitando condiciones. También se puede suscribir por separado para recibir notificaciones y reaccionar a dichos cambios.

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

    Arrastre de expresiones

    Los chips de condición se pueden reposicionar fácilmente utilizando los enfoques de reordenamiento de arrastrar y soltar del mouse o del teclado. Con ellos, los usuarios pueden ajustar su lógica de consulta de forma dinámica.

    • Arrastrar una ficha no modifica su condición/contenido, solo su posición.
    • El chip también se puede arrastrar a lo largo de grupos y subgrupos. Por ejemplo, la agrupación/desagrupación de expresiones se logra a través de la funcionalidad de arrastre de expresiones. Para agrupar las condiciones ya existentes, primero debe agregar un nuevo grupo a través del botón 'agregar' grupo. Luego, mediante el arrastre, las expresiones requeridas se pueden mover a ese grupo. Para desagrupar, puede arrastrar todas las condiciones fuera de su grupo actual y una vez que se elimine la última condición, el grupo se eliminará.

    Las fichas de un árbol de consulta no se pueden arrastrar en otro, por ejemplo, del padre al interno y viceversa.

    App Builder | CTA Banner

    Interacción con el teclado

    Combinaciones de teclas

    • Tab / Shift + Tab- navega al chip siguiente/anterior, indicador de arrastre, botón de eliminación, botón de expresión 'agregar'.
    • Arrow Down / Arrow Up- Cuando el indicador de arrastre del chip está enfocado, el chip se puede mover hacia arriba / abajo.
    • Space / Enter- La expresión enfocada entra en el modo de edición. Si se ha movido la ficha, esto confirma su nueva posición.
    • Esc- El reordenamiento de Chip se cancela y vuelve a su posición original.

    El reordenamiento del teclado proporciona la misma funcionalidad que la función de arrastrar y soltar del ratón. Una vez que se mueve una ficha, el usuario debe confirmar la nueva posición o cancelar el reorden.

    Plantillas

    El componente Generador de consultas de Ignite UI for Angular permite definir plantillas para el encabezado del componente y el valor de búsqueda utilizando los siguientes nombres de referencia predefinidos:

    Plantilla de encabezado

    De forma predeterminada, no se mostraría el IgxQueryBuilderComponent encabezado. Con el fin de definir tal, el IgxQueryBuilderHeaderComponent debe agregarse dentro de el igx-query-builder.

    Luego, para establecer el título del encabezado se podría usar la entrada y pasar el title contenido dentro del permite crear plantillas en el encabezado del generador de igx-query-builder-header consultas.

    El siguiente fragmento de código ilustra cómo hacerlo:

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

    Valor de búsqueda

    El valor de búsqueda de una condición se puede modelar usando la igxQueryBuilderSearchValue directiva, aplicada a un <ng-template> interior del cuerpo de la 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

    Formateador

    Para cambiar la apariencia del valor de búsqueda en el chip que se muestra cuando una condición no está en modo de edición, puede establecer una función de formateador en la matriz de campos. El valor de búsqueda y la condición seleccionada se pueden acceder a través de los argumentos value y rowData de la siguiente manera:

    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

    Manifestación

    Hemos creado este ejemplo de Angular Query Builder para mostrarle las funcionalidades de plantillas y formateador para el encabezado y el valor de búsqueda del componente Angular Query Builder.

    EXAMPLE
    TS
    HTML
    SCSS
    Edit in:

    Estilo

    Para comenzar a diseñar el Generador de consultas, necesitamos importar el archivo index, donde se encuentran todas las funciones del tema y los mixins de componentes:

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

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

    El Generador de consultas toma el color de fondo de su tema, utilizando el parámetro background. Para cambiar el fondo necesitamos crear un tema personalizado:

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

    Dado que tenemos otros componentes dentro del Generador de consultas, como botones, chips, menús desplegables y entradas, necesitamos crear un tema separado para cada uno:

    $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

    En este ejemplo, solo cambiamos algunos de los parámetros para los componentes enumerados, pero los button-theme​ ​chip-theme​ ​drop-down-theme​ ​input-group-theme temas proporcionan muchos más parámetros para controlar sus respectivos estilos.

    En lugar de codificar los valores de color como acabamos de hacer, podemos lograr una mayor flexibilidad en términos de colores mediante el uso de las palette funciones y color. Consulte el Palettes tema para obtener orientación detallada sobre cómo usarlos.

    El último paso es incluir los nuevos temas componentes utilizando la css-vars mezcla.

    @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

    Si el componente está usando un Emulated ViewEncapsulation, es necesario penetrate que esta encapsulación use::ng-deep para diseñar los componentes dentro del componente del generador de consultas (botón, chip, menú desplegable ... etcétera).

    Manifestación

    EXAMPLE
    TS
    HTML
    SCSS
    Edit in:

    La muestra no se verá afectada por el tema global seleccionado en Change Theme.

    También puede optimizar el desarrollo de su aplicación Angular utilizando WYSIWYG App Builder ™ con componentes de interfaz de usuario reales.

    Referencias de API

    Recursos adicionales

    Nuestra comunidad es activa y siempre da la bienvenida a nuevas ideas.