Angular Tree Grid Row Selection

Com a seleção de linha no Ignite UI for Angular, há uma coluna seletora de linha que precede todas as outras colunas dentro da linha. Quando um usuário clica no seletor de linha, a linha será selecionada ou desmarcada, permitindo que o usuário selecione várias linhas de dados.

Angular Row Selection Example

O exemplo abaixo demonstra os quatro tipos de comportamento de seleção de linha da Grade de Árvore. Use os botões abaixo para ativar cada um dos modos de seleção disponíveis. Uma breve descrição será fornecida em cada interação do botão por meio de uma caixa de mensagem de lanchonete. Use o botão de alternância para ocultar ou mostrar a caixa de seleção do seletor de linha.

Setup

Para configurar a seleção de linha no igx-tree-grid, você só precisa definir a propriedade rowSelection. Essa propriedade aceita a enumeração GridSelectionMode. GridSelectionMode expõe os quatro modos a seguir: none,single,multiple e multipleCascade. Abaixo, veremos cada um deles com mais detalhes.

None Selection

Por padrão, a seleção de linha está desabilitada igx-tree-grid, caso contrário ([rowSelection]="'none'"). Portanto, você não pode selecionar ou desmarcar uma linha por meio da interação com a interface do usuário da Grade de Árvore, a única maneira de concluir essas ações é usar os métodos de API fornecidos.

Single Selection

A seleção de linha única agora pode ser facilmente configurada, a única coisa que você precisa fazer é definir [rowSelection] = '"single"' a propriedade. Isso lhe dá a oportunidade de selecionar apenas uma linha dentro de uma grade. Você pode selecionar uma linha clicando em uma célula ou pressionando a tecla de espaço ao focar em uma célula da linha e, claro, pode selecionar uma linha clicando no campo seletor de linha. Quando a linha é selecionada ou desmarcada o evento rowSelectionChanging é emitido.

<!-- selectionExample.component.html -->

<igx-tree-grid [data]="data" primaryKey="ID" foreignKey="ParentID" [autoGenerate]="true"
            [rowSelection]="'single'" [allowFiltering]="true" (rowSelectionChanging)="handleRowSelection($event)">
</igx-tree-grid>

/* selectionExample.component.ts */

public handleRowSelection(event) {
    if (args.added.length && args.added[0] === 3) {
        args.cancel = true;
    }
}

Multiple Selection

Para habilitar a seleção de várias linhas, igx-tree-grid basta definir a rowSelection propriedade como multiple. Isso habilitará um campo seletor de linha em cada linha e no cabeçalho da grade de árvore. O seletor de linha permite que os usuários selecionem várias linhas, com a seleção persistindo por meio de operações de rolagem, paginação e dados, como classificação e filtragem. A linha também pode ser selecionada clicando em uma célula ou pressionando a tecla de espaço quando uma célula estiver focada. Se você selecionou uma linha e clicou em outra enquanto mantém pressionada a tecla shift, isso selecionará todo o intervalo de linhas. Neste modo de seleção, quando você clica em uma única linha, as linhas selecionadas anteriormente serão desmarcadas. Se você clicar enquanto segura a tecla ctrl, a linha será alternada e a seleção anterior será preservada.

<!-- selectionExample.component.html -->

<igx-tree-grid [data]="data" primaryKey="ID" foreignKey="ParentID" [rowSelection]="'multiple'"
        [allowFiltering]="true" (rowSelectionChanging)="handleRowSelection($event)" >
</igx-tree-grid>

Cascade Selection

Para habilitar a seleção de linha em cascata, igx-tree-grid basta definir a rowSelection propriedade como multipleCascade. Isso habilitará um campo seletor de linha em cada linha e no cabeçalho da grade de árvore. O seletor de linha permite que os usuários selecionem várias linhas que selecionariam todos os filhos na árvore abaixo. A seleção persiste por meio de operações de rolagem, paginação e dados, como classificação e filtragem. A linha também pode ser selecionada clicando em uma célula ou pressionando a tecla de espaço quando uma célula estiver focada. Se você selecionou uma linha e clicou em outra enquanto mantém pressionada a tecla shift, a seleção de um registro pai selecionará todos os seus filhos, mesmo que eles não estejam no intervalo selecionado. Neste modo de seleção, quando você clica em uma única linha, as linhas selecionadas anteriormente serão desmarcadas. Se você clicar enquanto segura a tecla ctrl, a linha e seus filhos serão alternados e a seleção anterior será preservada.

<!-- selectionExample.component.html -->

<igx-tree-grid [data]="data" primaryKey="ID" foreignKey="ParentID" [autoGenerate]="true"
        [rowSelection]="'multipleCascade'" [allowFiltering]="true" (rowSelectionChanging)="handleRowSelection($event)">
</igx-tree-grid>

Nesse modo, o estado de seleção de um pai depende inteiramente do estado de seleção de seus filhos. Quando um pai tem alguns filhos selecionados e alguns desmarcados, sua caixa de seleção está em um estado indeterminado.

<!-- selectionExample.component.ts -->

 public handleRowSelection(event: IRowSelectionEventArgs) {
    // use event.newSelection to retrieve primary key/row data of latest selected row
    this.selectedRowsCount = event.newSelection.length;
    this.selectedRowIndex = event.newSelection[0];
 }

Notas

A seleção de linha acionará o rowSelectionChanging evento. Este evento fornece informações sobre a nova seleção, a seleção antiga, as linhas que foram adicionadas e removidas da seleção antiga. Além disso, o evento pode ser cancelado, o que permite evitar a seleção.
Quando a seleção de linha está ativada, os seletores de linha são exibidos, mas se você não quiser mostrá-los, poderá definir [hideRowSelectors] = true.
Ao alternar entre os modos de seleção de linha em tempo de execução, isso limpará o estado de seleção de linha anterior.

API usage

Select rows programmatically

O trecho de código abaixo pode ser usado para selecionar uma ou várias linhas simultaneamente (via primaryKey); 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.

<!-- selectionExample.component.html -->

<igx-tree-grid ... [primaryKey]="'ID'">
...
</igx-tree-grid>
...
<button (click)="this.treeGrid.selectRows([1,2,5], true)">Select 1,2 and 5</button> // select rows and clear previous selection state

Isso adicionará as linhas que correspondem às entradas de dados com IDs 1, 2 e 5 à seleção de grade de árvore.

Deselect rows

Se você precisar desmarcar linhas programaticamente, poderá usar o deselectRows(rowIds: []) método.

<!-- selectionExample.component.html -->

<igx-tree-grid ... [primaryKey]="'ID'">
...
</igx-tree-grid>
...
<button (click)="this.treeGrid.deselectRows([1,2,5])">Deselect 1,2 and 5</button>

Row selection event

Quando há alguma alteração na seleção, o evento de seleção rowSelectionChanging de linha é emitido. rowSelectionChanging expõe os seguintes argumentos:

oldSelection- matriz de dados da linha que contém o estado anterior da seleção da linha.
newSelection- matriz de dados de linha que correspondem ao novo estado da seleção de linha.
added- matriz de dados da linha que estão atualmente adicionados à seleção.
removed- matriz de dados de linha que são removidos atualmente de acordo com o estado de seleção antigo.
event- o evento original que acionou a alteração na seleção de linha.
cancel- permite impedir a alteração da seleção de linha.

Evento de seleção de linha em cenários de dados remotos

Em cenários de dados remotos, quando a grade tiver um primaryKey argumento set,event rowSelectionChanging.oldSelection não conterá o objeto de dados de linha completa para as linhas que estão atualmente fora da exibição de dados. Nesse caso, rowSelectionChanging.oldSelection o objeto conterá apenas uma propriedade, que é o primaryKey campo. Para o restante das linhas, atualmente na exibição de dados, rowSelectionChanging.oldSelection conterá os dados da linha inteira.

<!-- selectionExample.component.html -->

<igx-tree-grid (rowSelectionChanging)="handleRowSelectionChange($event)">
...
</igx-tree-grid>

/* selectionExample.component.ts */

public handleRowSelectionChange(args) {
    args.cancel = true; // this will cancel the row selection
}

Select all rows

Outro método de API útil que igx-tree-grid fornece é selectAll(onlyFilteredData). Por padrão, esse método selecionará todas as linhas de dados, mas se a filtragem for aplicada, ele selecionará apenas as linhas que correspondem aos critérios de filtro. Mas se você chamar o método com o parâmetro false, selectAll(false) sempre selecionará todos os dados na grade, mesmo que a filtragem seja aplicada.

Note

Lembre-se de que selectAll() não selecionará as linhas que são excluídas.

Deselect all rows

igx-tree-grid provides deselectAll(onlyFilteredData) método, que, por padrão, desmarcará todas as linhas de dados, mas se a filtragem for aplicada, desmarcará apenas as linhas que correspondem aos critérios de filtro. Mas se você chamar o método com o parâmetro false, sempre limpará todo o estado de seleção de linha, deselectAll(false) mesmo que a filtragem seja aplicada.

How to get selected rows

Se você precisar ver quais linhas estão selecionadas no momento, poderá obter suas IDs de linha com o selectedRows getter.


public getSelectedRows() {
    const currentSelection = this.treeGrid.selectedRows; // return array of row IDs
}

Além disso, atribuir IDs de linha a selectedRows permitirá que você altere o estado de seleção da grade.

public mySelectedRows = ['Johnathan Winchester', 'Ana Sanders']; // an array of row IDs

<igx-tree-grid primaryKey="ID" rowSelection="multiple" [autoGenerate]="false" [selectedRows]="mySelectedRows" [data]="data">
    <igx-column [field]="'Name'"></igx-column>
    <igx-column [field]="'Title'"></igx-column>
</igx-tree-grid>

Row selector templates

Você pode modelar seletores de cabeçalho e linha na Grade de Árvore e também acessar seus contextos que fornecem funcionalidade útil para diferentes cenários.

Por padrão, a Grade de Árvore lida com todas as interações de seleção de linha no contêiner pai do seletor de linha ou na própria linha, deixando apenas a visualização de estado para o modelo. A substituição da funcionalidade básica geralmente deve ser feita usando o rowSelectionChanging evento. Caso você implemente um modelo personalizado com um click manipulador que substitui a funcionalidade base, você deve interromper a propagação do evento para preservar o estado de linha correto.

Modelo de linha

Para criar um modelo de seletor de linha personalizado, dentro do igx-tree-grid, declare uma <ng-template> diretiva with igxRowSelector. No modelo, você pode acessar a variável de contexto fornecida implicitamente, com propriedades que fornecem informações sobre o estado da linha.

A propriedade selected mostra se a linha atual está selecionada ou não, enquanto a propriedade index pode ser usada para acessar o índice da linha.

<ng-template igxRowSelector let-rowContext>
    {{ rowContext.index }}
    <igx-checkbox
        [checked]="rowContext.selected"
        [readonly]="true"
    ></igx-checkbox>
</ng-template>

A rowID propriedade pode ser usada para obter uma referência de uma igx-tree-grid linha. Isso é útil quando você implementa um click manipulador no elemento seletor de linha.

<ng-template igxRowSelector let-rowContext>
    <igx-checkbox (click)="onSelectorClick($event, rowContext.key)"></igx-checkbox>
</ng-template>

No exemplo acima, estamos usando um igx-checkbox e nos ligamos rowContext.selected à sua checked propriedade. Veja isso em ação em nosso Row Numbering Demo.

Header template

Para criar um modelo de seletor de cabeçalho personalizado, na Grade de Árvore, declare uma <ng-template> diretiva with igxHeadSelector. No modelo, você pode acessar a variável de contexto fornecida implicitamente, com propriedades que fornecem informações sobre o estado do cabeçalho.

A selectedCount propriedade mostra quantas linhas estão selecionadas no momento, enquanto totalCount mostra quantas linhas existem na Grade de Árvore no total.

<ng-template igxHeadSelector let-headContext>
    {{ headContext.selectedCount }} / {{ headContext.totalCount  }}
</ng-template>

As selectedCount propriedades and totalCount podem ser usadas para determinar se o seletor de cabeça deve ser verificado ou indeterminado (parcialmente selecionado).

<igx-tree-grid [data]="tGridData" primaryKey="ProductID" childDataKey="Products">
    <!-- ... -->
    <ng-template igxHeadSelector let-headContext>
        <igx-checkbox
            [checked]="headContext.selectedCount > 0 && headContext.selectedCount === headContext.totalCount"
            [indeterminate]="headContext.selectedCount > 0 && headContext.selectedCount !== headContext.totalCount">
        </igx-checkbox>
    </ng-template>
</igx-tree-grid>

Row Numbering Demo

Esta demonstração mostra o uso de seletores de cabeçalho e linha personalizados. O último usa rowContext.index para exibir números de linha e um igx-checkbox limite a rowContext.selected.

Conditional Selection Demo

Esta demonstração impede que algumas linhas sejam selecionadas usando o evento e um modelo personalizado com caixa de seleção desativada rowSelectionChanging para linhas não selecionáveis.

API References

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.