React Grid Agrupar por

    O comportamento Ignite UI for React Agrupar por em React IgrGrid cria linhas de dados agrupadas com base nos valores da coluna. O Agrupar por no IgrGrid permite visualizar os grupos em uma estrutura hierárquica. As linhas de dados agrupadas podem ser expandidas ou recolhidas e a ordem de agrupamento pode ser alterada por meio da interface do usuário ou da API. Quando a Seleção de linha está ativada, um seletor de linha Agrupar por é renderizado na área mais à esquerda da linha do grupo. Caso a propriedade seja definida como única, as rowSelection caixas de seleção são desativadas e servem apenas como uma indicação para o grupo onde a seleção é colocada. Se a rowSelection propriedade estiver definida como múltipla, clicar no seletor de linha Agrupar por selecionará todos os registros pertencentes a esse grupo.

    React Grid Group By Example

    Este exemplo apresenta os recursos de agrupamento de uma grande quantidade de dados. Arrastar os cabeçalhos de coluna para o topo (área de agrupamento) permite que os usuários vejam os dados da coluna selecionada em uma estrutura hierárquica. Eles podem agrupar por em vários campos arrastando mais cabeçalhos de coluna para o topo. Essas opções de agrupamento são úteis quando você tem tabelas com várias linhas e colunas nas quais os usuários desejam apresentar os dados de uma forma muito mais rápida e visualmente aceitável.

    Initial Grouping State

    É possível definir o agrupamento inicial da grade atribuindo uma matriz de expressões à groupingExpressions propriedade da grade.

    const expressions = [
    { fieldName: 'ProductName', dir: SortingDirection.Desc },
    { fieldName: 'Released', dir: SortingDirection.Desc }
];

function App() {
    const grid1Ref = useRef();
    return (
    <>
        <IgrGrid
            autoGenerate="true"
            groupingExpressions={expressions}
            ref={grid1Ref}>
        </IgrGrid>
    </>
    )
}

    Expressões de agrupamento implementam a interface ISortingExpression.

    Group By API

    Grouping API

    O agrupamento está disponível por meio da IU e por meio de uma API robusta exposta pelo componente grid. Os desenvolvedores podem permitir que os usuários finais agrupem os dados da grade por determinadas colunas, definindo a propriedade Groupable de cada coluna como true.

    function App() {
    const gridRef = useRef();
    return (
    <>
        <IgrGrid
            autoGenerate="false"
            ref={gridRef}
            >
            <IgrColumn field="OrderID" hidden="true"></IgrColumn>
            <IgrColumn field="ShipCountry" header="Ship Country" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="OrderDate" header="Order Date" dataType="date" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="PostalCode" header="Postal Code" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="Discontinued" width="200px" dataType="boolean" groupable="true"></IgrColumn>
            <IgrColumn field="ShipName" header="Ship Name" width="200px" groupable="false"></IgrColumn>
            <IgrColumn field="ShipCity" header="Ship City" width="200px" groupable="false"></IgrColumn>
            <IgrColumn field="ShipperName" header="Shipper Name" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="Salesperson" header="Sales Person" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="UnitPrice" header="Unit Price" width="200px" groupable="true"></IgrColumn>
            <IgrColumn field="Quantity" width="200px" groupable="true"></IgrColumn>
        </IgrGrid>
    </>
  )
}

    Durante o tempo de execução, as expressões são gettable e settable da groupingExpressions propriedade. Se você precisar adicionar ou alterar uma expressão existente, também poderá usar o groupBy método com uma única expressão ou uma matriz de expressões.

    gridRef.current.groupBy([{ fieldName: 'ProductName', dir: SortingDirection.Desc, ignoreCase: true }]);

    Expand/Collapse API

    Além de agrupar expressões, você também pode controlar os estados de expansão para linhas de grupo. Eles são armazenados em uma propriedade separada do IgrGrid componente groupingExpansionState que é uma coleção de IgrGroupByExpandState. Cada estado de expansão é definido exclusivamente pelo nome do campo para o qual é criado e pelo valor que representa para cada nível de agrupamento, ou seja, o identificador é uma matriz hierárquica de IgrGroupByKey.

    Assim como na groupingExpressions configuração, definir uma lista de IgrGroupByExpandState diretamente para o groupingExpansionState mudará a expansão de acordo. IgrGrid Além disso, expõe um método toggleGroup que alterna um grupo pela instância de registro de grupo ou por meio da expanded propriedade da linha.

        const groupRow = gridRef.current.getRowByIndex(0).groupRow;
    gridRef.current.toggleGroup(groupRow);

        const groupRow = gridRef.current.getRowByIndex(0);
    groupRow.expanded = false;

    Os grupos podem ser criados expandidos (padrão) ou recolhidos e os estados de expansão geralmente contêm apenas o estado oposto ao comportamento padrão. Você pode controlar se os grupos devem ser criados expandidos ou não por meio da groupsExpanded propriedade.

    Select/Deselect All Rows in a Group API

    Selecionar/desmarcar todas as linhas em um grupo está disponível por meio dos selectRowsInGroup métodos e deselectRowsInGroup API.

    O snippet de código abaixo pode ser usado para selecionar todas as linhas dentro de um grupo usando o método de instância selectRowsInGroup de registro de grupo. Além disso, o segundo parâmetro desse método é uma propriedade booleana por meio da qual você pode escolher se a seleção de linha anterior será desmarcada ou não. A seleção anterior é preservada por padrão.

        const groupRow = gridRef.current.getRowByIndex(0).groupRow;
    gridRef.current.selectRowsInGroup(groupRow);

    Se você precisar desmarcar todas as linhas dentro de um grupo programaticamente, poderá usar o deselectRowsInGroup método.

        const groupRow = gridRef.current.getRowByIndex(0).groupRow;
    gridRef.current.deselectRowsInGroup(groupRow);

    Templating

    Group Row Templates

    A linha de grupo, exceto para a interface do usuário de expansão/recolhimento, é totalmente passível de modelo. Por padrão, ele renderiza um ícone de agrupamento e exibe o nome do campo e o valor que ele representa. O contexto para renderizar o modelo é do tipo IgrGroupByRecord.

    Como exemplo, o modelo a seguir tornaria o resumo das linhas do grupo mais detalhado:

    function template(ctx: { dataContext: IgrGroupByRowTemplateContext }) {
    const groupRow = ctx.dataContext.implicit;
    return (<>
       <span>Total items with value: { groupRow.value } are { groupRow.records.length }</span>
    </>)
}

    Group Row Selector Templates

    Como mencionado acima, a linha do grupo, exceto a interface do usuário de expansão/recolhimento, é totalmente modelável. Para criar um modelo de seletor de linha Agrupar por personalizado, use groupByRowSelectorTemplate. No modelo, você pode acessar a variável de contexto fornecida implicitamente, com propriedades que fornecem informações sobre o estado da linha Agrupar por.

    A propriedade SelectedCount mostra quantos registros do grupo estão selecionados no momento, enquanto TotalCount mostra quantos registros pertencem ao grupo.

    function template(ctx: { dataContext: IgrGroupByRowSelectorTemplateContext }) {
    return (<>
        { ctx.dataContext.implicit.selectedCount } / { ctx.dataContext.implicit.totalCount }
    </>)
}

    A propriedade GroupRow retorna uma referência à linha do grupo.

    function template(ctx: { dataContext: IgrGroupByRowSelectorTemplateContext }) {
    const groupRow = ctx.dataContext.implicit.groupRow;
    return (<>
        <div onClick={(e: any) => handleGroupByRowSelectorClick(e, groupRow)}>Handle groupRow</div> `;
    </>)
}

    As propriedades SelectedCount e TotalCount podem ser usadas para determinar se o seletor de linha Group By deve ser verificado ou indeterminado (parcialmente selecionado).

    React Grid Group By With Paging

    As linhas de grupo participam do processo de paginação junto com as linhas de dados. Elas contam para o tamanho de página para cada página. As linhas recolhidas não são incluídas no processo de paginação. Qualquer operação de expansão ou recolhimento força o Paging a recalcular a contagem de páginas e ajustar o índice de página, se necessário. Os grupos que abrangem várias páginas são divididos entre elas. A linha de grupo é visível apenas na página em que começa e não é repetida nas páginas subsequentes. As informações de resumo para linhas de grupo são calculadas com base no grupo inteiro e não são afetadas pelo Paging.

    React Group By With Paging Example

    Group By With Summaries

    A integração entre Agrupar por e Resumos é descrita no tópico Resumos.

    Keyboard Navigation

    A interface de agrupamento oferece suporte às seguintes interações de teclado:

    • Para linhas de grupo (o foco deve estar na linha ou na célula de expansão/recolhimento)

      • ALT + DIREITA- Expande o grupo
      • ALT + ESQUERDA- Recolhe o grupo
      • ESPAÇO- seleciona todas as linhas no grupo, se a propriedade rowSelection estiver definida como múltipla

    • Para componentes do grupo IgrChip na área agrupada por (o foco deve estar no chip)

      • SHIFT + ESQUERDA- move a ficha em foco para a esquerda, alterando a ordem de agrupamento, se possível
      • SHIFT + DIREITA- move o chip em foco para a direita, alterando a ordem de agrupamento, se possível
      • ESPAÇO- altera a direção da classificação
      • DELETE- desagrupa o campo
      • Os elementos separados do chip também são focalizáveis e podem ser interagidos usando a tecla ENTER.

    React Grid Custom Group By

    A grade permite definir o agrupamento personalizado por coluna ou por expressão de agrupamento, que fornece agrupamento com base em uma condição personalizada. Isso é útil quando você precisa agrupar por objetos complexos ou para outros cenários específicos do aplicativo.

    O exemplo abaixo demonstra o agrupamento personalizado por Date, em que os valores de data são classificados e agrupados por Dia, Semana, Mês ou Ano com base no modo de agrupamento selecionado pelo usuário.

    React Custom Group By Example

    O exemplo define a classificação personalizada para as diferentes condições de data. Cada estratégia personalizada define o GroupingComparer método, que é a função de comparação personalizada usada ao classificar os valores. Além disso, extrai os valores da data necessária para a comparação.

    const groupByMode = "Month";
function getParsedDate(date: any) {
    return {
        day: date.getDay(),
        month: date.getMonth() + 1,
        year: date.getFullYear()
    };
}

    Uma GroupingComparer função é definida para as expressões de agrupamento, que determina os itens pertencentes ao mesmo grupo com base no modo de agrupamento selecionado. Os valores nos dados classificados para os quais essa função retorna 0 são marcados como parte do mesmo grupo.

    grid.groupingExpressions = [
    { fieldName: 'OrderDate', dir: SortingDirection.Desc,
    groupingComparer: (a, b) => {
            const dateA = this.getParsedDate(a);
            const dateB = this.getParsedDate(b);
            if (this.groupByMode === 'Month') {
                return dateA.month === dateB.month ? 0 : -1;
            } else if (this.groupByMode === "Year") {
                return dateA.year === dateB.year ? 0 : -1;
            } else if (this.groupByMode === 'Week') {
                return this.getWeekOfDate(a) === this.getWeekOfDate(b) ? 0 : -1;
            }
            return dateA.day === dateB.day && dateA.month === dateB.month ? 0 : -1;
        }
    }
];

    Styling

    Além dos temas predefinidos, a grade pode ser ainda mais personalizada ao definir algumas das propriedades CSS disponíveis. Caso você queira alterar algumas das cores, precisa definir uma classe para a grade primeiro:

    function App() {
     return (
        <IgrGrid className="grid">
        </IgrGrid>
    )
}

    Em seguida, defina as propriedades CSS relacionadas para essa classe:

    .grid {
    --ig-grid-group-row-background: #969799;
    --ig-grid-group-row-selected-background: #969799;
    --ig-grid-group-label-column-name-text: #f8f8f8;
    --ig-grid-group-label-text: #f8f8f8;
    --ig-grid-group-count-text-color: #222;
    --ig-grid-expand-icon-color: #f8f8f8;
    --ig-grid-expand-icon-hover-color: #f8f8f8;
}

    Demo

    Known Limitations

    Limitação Descrição
    A quantidade máxima de colunas agrupadas é 10. Se mais de 10 colunas forem agrupadas, um erro será gerado.

    API References

    Additional Resources

    Nossa comunidade é ativa e sempre acolhedora para novas ideias.