Grille de données

Le composant UDDataGrid est une version avancée du tableau qui est utile pour afficher de grandes quantités de données. Il prend en charge plusieurs des mêmes fonctionnalités que le tableau, mais offre également un filtrage complexe, la virtualisation des lignes, le tri multicolonne et plus encore.

Grille de données simple

Les grilles de données chargent leurs données via le gestionnaire d'événement -LoadRows. Vous devrez retourner une table de hachage qui contient les données des lignes et le nombre total de lignes.

Les colonnes sont définies à l'aide de tables de hachage.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random}
        @{ Name = 'Tom'; Number = Get-Random}
        @{ Name = 'Sarah'; Number = Get-Random}
    )
    $Data | Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Colonnes

Les colonnes sont personnalisables à l'aide de New-UDDataGridColumn. Vous trouverez plus d'information sur cette applet de commande ici.

Rendu de colonnes personnalisées

Vous pouvez rendre des composants personnalisés dans les colonnes en spécifiant render dans la table de hachage de la colonne. Vous pouvez accéder aux données de la ligne actuelle en utilisant la variable $EventData ou $Row

Dans cet exemple, le nombre est affiché dans la colonne du nom avec un composant New-UDTypography.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    }
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
         New-UDTypography $EventData.number 
    }
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Colonnes à largeur flexible

La fluidité ou la réactivité des colonnes peut être obtenue en définissant la propriété flex d'une colonne.

La propriété flex accepte une valeur entre 0 et ∞. Elle fonctionne en divisant l'espace restant dans la grille entre toutes les colonnes flex proportionnellement à leur valeur flex.

Par exemple, considérez une grille d'une largeur totale de 500 px qui comporte trois colonnes : la première avec width: 200; la deuxième avec flex: 1; et la troisième avec flex: 0.5. La première colonne aura une largeur de 200 px, laissant 300 px restants. La colonne avec flex: 1 est deux fois la taille de flex: 0.5, ce qui signifie que les tailles finales seront : 200 px, 200 px, 100 px.

Pour définir une largeur minimale et maximale pour une colonne flex, définissez les propriétés minWidth et maxWidth sur la colonne.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = "This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string."}
    }        
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
         New-UDTypography $EventData.number 
    }
    New-UDDataGridColumn -Field number -Flex 1.0
) -AutoHeight $true

Dimensionnement automatique des colonnes

Si vous souhaitez laisser la grille de données dimensionner automatiquement la largeur des colonnes, vous pouvez utiliser le paramètre -AutoSizeColumns de New-UDDataGrid. La grille de données évaluera la taille des données et déterminera la meilleure taille pour les colonnes après le chargement des données. Cela peut provoquer un réarrangement de l'interface après le chargement des données.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = "This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string."}
    }        
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
         New-UDTypography $EventData.number 
    }
    New-UDDataGridColumn -Field number
) -AutoHeight $true -AutoSizeColumns

LoadRows

Le paramètre -LoadRows est utilisé pour retourner des données pour la grille de données. L'état du tableau sera fourni au gestionnaire d'événement sous forme de $EventData. Vous trouverez les propriétés suivantes dans l'objet $EventData.

Propriété	Description	Type
Filter	Un objet de filtre que vous pouvez utiliser pour construire des filtres sur vos données.	Table de hachage
Page	La page actuelle. Commence à 0.	Entier
PageSize	Le nombre d'enregistrements dans une page.	Entier
Sort	Les options de tri pour le tableau	Table de hachage

Pagination

Pour implémenter la pagination, vous pouvez accéder aux propriétés page et pageSize de la variable $EventData. Si vous utilisez une source de données distante, vous voudrez implémenter une logique de pagination personnalisée. Voici un exemple d'utilisation des propriétés de pagination pour parcourir les lignes localement. Selon votre source de données (p. ex. SQL), vous pourriez parcourir les données différemment.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    } 
    
    $Rows = $Rows | Select-Object -First $EventData.pageSize -Skip ($EventData.Page * $EventData.PageSize)
    
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true -Pagination

Out-UDDataGridData implémente automatiquement la pagination, et vous n'avez pas besoin de faire ce qui précède si toutes vos données sont en mémoire. Ce qui précède sert uniquement à des fins de démonstration.

Filtrage

La grille de données prend en charge le filtrage des données selon chaque colonne. Plusieurs filtres peuvent être définis pour permettre à l'utilisateur de restreindre l'ensemble de données affiché. Par défaut, l'applet de commande Out-UDDataGridData implémente le filtrage pour les données locales. Lorsque vous utilisez une source de données distante, comme SQL, il est suggéré d'implémenter un filtrage personnalisé afin d'améliorer l'expérience utilisateur et la performance.

Structure de données du filtre

L'objet de filtre est inclus dans le $EventData du gestionnaire d'événement -LoadRows lorsqu'un filtre est défini. L'objet a une structure comme suit.

@{
    items = @(
        @{ 
            field = "Name"
            operator = "contains"
            value = "test"
        }
    )
    logicOperator = "and"
    quickFilterValues = @("test")
    quickFilterLogicOperator = "and"
}

Items

La propriété items contient une collection de champs, d'opérateurs et de valeurs. Vous pouvez les utiliser pour filtrer vos données.

Propriété	Description	Type
Field	Le nom du champ à filtrer	Chaîne
Operator	Le type d'opérateur à utiliser lors du filtrage des données.	Chaîne
Value	La valeur utilisée pour filtrer	Objet

LogicOperator

Le champ de l'opérateur logique est utilisé pour spécifier le lien entre les filtres. Ce peut être and ou or.

QuickFilterValues

Contient une collection de valeurs de filtre rapide que vous pouvez choisir d'appliquer à vos données.

QuickFilterLogicOperator

Contient l'opérateur logique pour les valeurs de filtre rapide spécifiées par l'utilisateur. Ce peut être and ou or.

Filtre personnalisé

L'applet de commande Out-UDDataGridData fournit une implémentation du filtrage pour les données statiques. Si vous utilisez cette applet de commande, vous n'avez pas besoin d'implémenter le filtrage manuellement. Si vous avez une source de données distante, vous voudrez fournir une implémentation personnalisée pour le filtrage. Voici un exemple d'utilisation de la structure de filtre dans $EventData pour éliminer des lignes en fonction des filtres fournis par l'utilisateur.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    }

    foreach($filter in $eventData.Filter.items)
    {
        if ($filter.operator -eq 'equals')
        {
            $Rows = $Rows | Where-Object $filter.field -eq $filter.value
        }
        elseif ($filter.operator -eq 'contains')
        {
            $Rows = $Rows | Where-Object $filter.field -match $filter.value
        }
    }

    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Filtre rapide personnalisé

Le filtre rapide est semblable à une simple boîte de recherche. Vous pouvez activer le filtrage rapide avec le paramètre -ShowQuickFilter sur New-UDDataGrid. Une boîte de recherche apparaîtra en haut à droite de la grille de données. Lorsque l'utilisateur saisit une valeur dans la grille de données, l'information du filtre rapide sera fournie.

Voici un exemple d'utilisation des filtres rapides. Out-UDDataGridData implémente le filtrage rapide et n'est pas requis lorsque vous utilisez des données locales. Ce qui suit est présenté à titre de démonstration seulement.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    }

    foreach($filter in $eventData.QuickFilterValues)
    {
        $Rows = $Rows | Where-Object $filter.field -match $filter
    }

    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true

Tri

L'objet $EventData contiendra une propriété Sort lorsque l'utilisateur trie la grille de données. Elle contient des propriétés pour chaque colonne triée. Les propriétés commenceront à 0 et s'incrémenteront à mesure que d'autres colonnes seront triées.

Par exemple, vous pouvez accéder à la première colonne triée comme suit.

$EventData.Sort.'0'.field

Vous recevrez également la direction du tri pour chaque colonne.

Propriété	Description	Type
Field	Le champ à trier.	Chaîne
Sort	La direction du tri du champ.	asc, desc

Contenu détaillé

Vous pouvez utiliser le gestionnaire d'événement -LoadDetailContent pour afficher de l'information supplémentaire sur la ligne que vous développez. L'information sur la ligne actuelle est disponible dans $EventData.row.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random }
        @{ Name = 'Tom'; Number = Get-Random }
        @{ Name = 'Sarah'; Number = Get-Random }
    )
    $Data| Out-UDDataGridData -Context $EventData -TotalRows $Data.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true -LoadDetailContent {
    Show-UDToast $Body
    New-UDAlert -Text $EventData.row.Name
}

Exemple : Grilles de données imbriquées

Vous pouvez utiliser le paramètre -LoadDetailContent pour rechercher des données imbriquées à propos d'un objet. Dans cet exemple, nous chargeons une grille de données de machines virtuelles et affichons le nom, le système d'exploitation, la mémoire et les cœurs de processeur. Le développement du contenu détaillé fournit une grille de données des cartes réseau disponibles sur la machine virtuelle. Nous utilisons des données fictives dans cet exemple, mais vous pourriez utiliser n'importe quelle applet de commande disponible dans PowerShell Universal.

function Get-VirtualMachine {
    1..10 | ForEach-Object {
        [PSCustomObject]@{
            Name = "VM-$_"
            OperatingSystem = @("Windows Server 2019", "Windows Server 2022", "Ubuntu 20.02") | Get-Random
            Memory = @(64, 128, 512, 1024) | Get-Random
            Cores = @(8, 16, 32) | Get-Random
        }
    }
}

function Get-NetworkCard {
    param($VirtualMachine)

    1..4 | ForEach-Object {
        [PSCustomObject]@{
            Name = "NIC-$_"
            Speed = @(64, 128, 512, 1024) | Get-Random
        }
    }
}

New-UDApp -Content { 
    New-UDDataGrid -LoadRows {
        $VMs = Get-VirtualMachine
        $VMs| Out-UDDataGridData -Context $EventData -TotalRows $VMs.Length
    } -Columns @(
        New-UDDataGridColumn -Field Name
        New-UDDataGridColumn -Field OperatingSystem
        New-UDDataGridColumn -Field Memory -Render {
            New-UDTypography -Text "$($EventData.Memory) GB\s"
        }
        New-UDDataGridColumn -Field Cores
    ) -AutoHeight $true -LoadDetailContent {
        $VirutalMachine = $EventData.row
        New-UDDataGrid -LoadRows {
            $NICs = Get-NetworkCard -VirtualMachine $VirutalMachine
            $NICs | Out-UDDataGridData -Context $EventData -TotalRows $NICs.Length
        } -Columns @(
            New-UDDataGridColumn -Field Name
            New-UDDataGridColumn -Field Speed -Render {
                New-UDTypography -Text "$($EventData.Speed) GB\s"
            }
        ) -AutoHeight $true
    }
}

Modification

Les tableaux offrent la prise en charge de l'éditeur en spécifiant le gestionnaire d'événement -OnEdit. Les nouvelles données de ligne seront fournies sous forme de $EventData. Vous pouvez choisir de retourner l'information de ligne mise à jour (par exemple, ajuster quelque chose que l'utilisateur a saisi) et la retourner depuis le gestionnaire d'événement. Si vous ne retournez rien, la ligne reflétera ce que l'utilisateur a saisi.

Le $EventData a le format suivant.

@{
    newRow = @{}
    oldRow = @{}
}

Assurez-vous de fournir la propriété editable à chaque colonne que vous souhaitez que l'utilisateur puisse modifier.

$Cache:Data = @(
    @{ Name = 'Adam'; number = Get-Random }
    @{ Name = 'Tom'; number = Get-Random }
    @{ Name = 'Sarah'; number = Get-Random }
)

New-UDDataGrid -LoadRows {
    $Cache:Data| Out-UDDataGridData -Context $EventData -TotalRows $Cache:Data.Length
} -Columns @(
    New-UDDataGridColumn -Field name -Render {
        New-UDButton -Text $EventData.number
    }
    New-UDDataGridColumn -Field number -Editable
) -AutoHeight $true -OnEdit {
    $Cache:Data | Where-Object { $_.Name -eq $EventData.NewRow.Name } | ForEach-Object {
        $_.Number = $EventData.NewRow.Number
    }
}

Sélection

Vous pouvez activer la sélection de lignes à l'aide du paramètre -CheckboxSelection pour afficher des cases à cocher pour les lignes à sélectionner. La sélection de lignes nécessite un ID déterministe pour les lignes de données fournies. Dans l'exemple ci-dessous, vous verrez que chaque ligne a un ID spécifique défini.

New-UDApp -Content { 
    $Rows = 1..100 | % {
        @{ Id = $_; Name = 'Adam'; Number = Get-Random}
    } 
    New-UDDataGrid -id DataGrid -LoadRows {  
    $Rows| Out-UDDataGridData -Context $EventData -TotalRows $Rows.Length
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -AutoHeight $true -Pagination -CheckboxSelection -CheckboxSelectionVisibleOnly -DisableRowSelectionOnClick

Vous pouvez accéder aux données sélectionnées avec le gestionnaire d'événement -OnSelectionChange ou en récupérant les ID de ligne via Get-UDElement.

New-UDButton -Text 'Get Selected Rows' -OnClick {
   $Value = Get-UDElement -ID 'DataGrid'
   Show-UDToast $Value.selection
}

Exportation personnalisée

Pour remplacer la fonctionnalité d'exportation par défaut, utilisez le gestionnaire d'événement -OnExport. $EventData sera le même objet de contexte utilisé pour -LoadRows. Vous devriez utiliser Out-UDDataGridExport pour retourner les données depuis -OnExport.

$Data = @(
    @{ name = 'Adam'; Number = Get-Random}
    @{ name = 'Tom'; Number = Get-Random}
    @{ name = 'Sarah'; Number = Get-Random}
)

New-UDDataGrid -LoadRows {
    @{
        rows = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -OnExport {
    $ExportContent = $Data | ConvertTo-Csv -NoTypeInformation | Out-String
    Out-UDDataGridExport -Data $ExportContent -FileName 'export.csv' 
}

Types d'exportation multiples

Lorsque vous utilisez une exportation personnalisée, vous pouvez utiliser le paramètre -ExportOptions pour définir plusieurs types d'exportation. Lorsque l'utilisateur sélectionne le type d'exportation, vous pouvez vérifier la propriété Type de $EventData pour déterminer quel type d'exportation produire.

$Data = @(
    @{ name = 'Adam'; Number = Get-Random}
    @{ name = 'Tom'; Number = Get-Random}
    @{ name = 'Sarah'; Number = Get-Random}
)

New-UDDataGrid -LoadRows {
    @{
        rows = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    New-UDDataGridColumn -Field name
    New-UDDataGridColumn -Field number
) -OnExport {
    if ($EventData.Type -eq 'CSV')
    {
        $ExportContent = $Data | ConvertTo-Csv -NoTypeInformation | Out-String
        Out-UDDataGridExport -Data $ExportContent -FileName 'export.csv' 
    }
} -ExportOptions @("CSV", "PDF")

Exemple : Données statiques

Dans cet exemple, nous générons un tableau de 10 000 enregistrements. Nous créerons une nouvelle fonction, Out-UDDataGridData, pour gérer la pagination, le tri et le filtrage. Cette fonction est déjà incluse dans le module Universal.

New-UDApp -Title 'PowerShell Universal' -Content {
     $Data =  1..10000 | % {
        @{ Name = 'Adam'; Number = Get-Random }
    } 
    New-UDDataGrid -LoadRows {  
      $Data | Out-UDDataGridData -Context $EventData
    } -Columns @(
        New-UDDataGridColumn -Field name
        New-UDDataGridColumn -Field number -Render {
                    New-UDButton -Icon (New-UDIcon -Icon User) -OnClick { Show-UDToast $EventData.Name } 
        }
    ) -AutoHeight $true -Pagination -HeaderFilters
}     

Exemple : Données SQL

Dans cet exemple, nous interrogerons la base de données PowerShell Universal avec dbatools.

function Out-UDSQLDataGrid {
    param(
        $Context,
        [Parameter(Mandatory)]
        [string]$Table,
        [Parameter(Mandatory)]
        [string]$SqlInstance,
        [Parameter(Mandatory)]
        [string]$Database,
        [Parameter(Mandatory)]
        [pscredential]$SqlCredential,
        [Int32]$RowsPerPage
    )

    End {
        $simpleFilter = @()

        if ($null -ne $Context.Filter.Items -and $Context.Filter.Items.Count -gt 0) {
            $logicOperator = $Context.Filter.logicOperator #The link operator is 'AND' or 'OR'. It will always be one or the other for all properties

            foreach ($item in $Context.Filter.Items) {         
                $simpleFilter += [PSCustomObject]@{
                    Property = $item.Field
                    Value    = $item.Value
                    Operator = $item.Operator
                }
            }
        }

        if ($null -ne $simpleFilter -and $simpleFilter.Count -gt 0) {
            $count = 1
            foreach ($filter in $simpleFilter) {
                if ($count -gt 1) {               
                    $SqlFilter += " $($logicOperator) "
                }
                else {
                    $SqlFilter += " WHERE "
                }

                switch ($filter.Operator) {
                    "contains" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)%' " }
                    "equals" { $SqlFilter += " $($filter.Property) = '$($filter.Value)' " }
                    "startsWith" { $SqlFilter += " $($filter.Property) LIKE '$($filter.Value)%' " }
                    "endsWith" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)' " }
                    "isAnyOf" {
                        $count = 1
                        foreach ($val in $filter.Value) {
                            if ($count -gt 1) {
                                $list += ", '$val'"
                            }
                            else {
                                $list += "'$val'"
                            }  
                            $count += 1
                        }
                        $SqlFilter += " $($filter.Property) IN ($($list)) "
                    }
                    "isempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NULL " }
                    "isnotempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NOT NULL " }
                    "notequals" { $SqlFilter += " $($filter.Property) != '$($filter.Value)' " }
                    "notcontains" { $SqlFilter += " $($filter.Property) NOT LIKE '%$($filter.Value)%' " }
                }
                $count += 1
            }
        }
        else {
            $SqlFilter = $null
        }

        if ($null -eq $SqlFilter) {
            $totalCount = (Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query "SELECT COUNT(*) As Count FROM $Table").Count
        }
        else {
            $totalCount = (Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query "SELECT COUNT(*) As Count FROM $Table $SqlFilter").Count
            $sort = $Context.Sort.'0'
        }

        if ($sort) {
            $sqlSort = "ORDER BY $($sort.field) $($sort.Sort) "
        }
        else {
            $sqlSort = "ORDER BY (SELECT NULL)"
        }

        if ($null -ne $SqlFilter) {
            $sqlPage = "OFFSET $($Context.Page * $Context.PageSize) ROWS FETCH NEXT $($Context.PageSize) ROWS ONLY;"
            $Query = "SELECT * FROM $Table $sqlFilter $sqlSort $sqlPage"
        }
        else {
            $sqlPage = "OFFSET $($RowsPerPage) ROWS FETCH NEXT $($RowsPerPage) ROWS ONLY;"
            $Query = "SELECT * FROM $Table $sqlSort $sqlPage"
        }

        $Rows = Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -SqlCredential $SqlCredential -Query $Query -As PSObject

        @{
            rows     = [Array]$Rows
            rowCount = $TotalCount
        }
    }   
}

New-UDDashboard -Title 'PowerShell Universal' -Content {
    New-UDDataGrid -LoadRows {  
      Out-UDSqlDataGrid -Context $EventData -SqlInstance "(localdb)\MSSQLLocalDb" -Database "PSU" -Table "Job"
    } -Columns @(
        New-UDDataGridColumn -Field id
        New-UDDataGridColumn -Field startTime
        New-UDDataGridColumn -Field status -Render {
          if ($EventData.Status -eq 2) {
                New-UDAlert -Severity 'Success' -Text 'Success'
            }

            if ($EventData.Status -eq 3) {
                New-UDAlert -Severity 'Error' -Text 'Failed'
            }
        }
    ) -AutoHeight $true -Pagination
}

API

• New-UDDataGrid
• New-UDDataGridColumn
• Out-UDDataGridData
• Out-UDDataGridExport