Grille de données

Composant de grille de données pour Universal Apps.

Le composant UDDataGrid est une version avancée du tableau, utile pour afficher de grandes quantités de données. Il prend en charge de nombreuses fonctionnalités similaires à celles du tableau, mais offre également un filtrage complexe, la virtualisation des lignes, le tri multi-colonnes et bien plus encore.

Grille de données simple

Les grilles de données chargent leurs données via le gestionnaire d'événements -LoadRows. Vous devez retourner une table de hachage contenant 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. Pour plus d'informations sur cette cmdlet, consultez cette page.

Rendu de colonnes personnalisées

Vous pouvez afficher 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 flexibles, proportionnellement à leur valeur flex.

Par exemple, considérez une grille d'une largeur totale de 500 px comportant 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 plus large que 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 ajuster 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 entraîner un réarrangement de l'interface utilisateur 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 les données de la grille de données. L'état du tableau sera fourni au gestionnaire d'événements sous la forme $EventData. Vous trouverez les propriétés suivantes dans l'objet $EventData.

Property	Description	Type
Filter	Un objet de filtre que vous pouvez utiliser pour construire des filtres sur vos données.	Hashtable
Page	La page actuelle. Commence à 0.	Integer
PageSize	Le nombre d'enregistrements par page.	Integer
Sort	Les options de tri pour le tableau.	Hashtable

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 souhaiterez implémenter une logique de pagination personnalisée. Vous trouverez ci-dessous 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 paginer 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 d'effectuer ce qui précède si toutes vos données sont en mémoire. L'exemple ci-dessus est uniquement fourni à des fins de démonstration.

Filtrage

La grille de données prend en charge le filtrage des données par colonne. Plusieurs filtres peuvent être définis pour permettre à l'utilisateur de restreindre le jeu de données affiché. Par défaut, la cmdlet Out-UDDataGridData implémente le filtrage pour les données locales. Lors de l'utilisation d'une source de données distante, comme SQL, il est recommandé d'implémenter un filtrage personnalisé pour améliorer l'expérience utilisateur et les performances.

Structure des données de filtre

L'objet de filtre est inclus dans $EventData pour le gestionnaire d'événements -LoadRows lorsqu'un filtre est défini. L'objet a la structure suivante.

@{
    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.

Property	Description	Type
Field	Le nom du champ à filtrer.	String
Operator	Le type d'opérateur à utiliser lors du filtrage des données.	String
Value	La valeur utilisée pour le filtrage.	Object

LogicOperator

Le champ d'opérateur logique est utilisé pour spécifier le lien entre les filtres. Il 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. Il peut être and ou or.

Filtre personnalisé

La cmdlet Out-UDDataGridData fournit une implémentation du filtrage pour les données statiques. Si vous utilisez cette cmdlet, vous n'avez pas besoin d'implémenter le filtrage manuellement. Si vous disposez d'une source de données distante, vous souhaiterez fournir une implémentation personnalisée pour le filtrage. Vous trouverez ci-dessous 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 similaire à une simple zone de recherche. Vous pouvez activer le filtrage rapide avec le paramètre -ShowQuickFilter sur New-UDDataGrid. Une zone 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, les informations de filtre rapide seront fournies.

Vous trouverez ci-dessous un exemple d'utilisation des filtres rapides. Out-UDDataGridData implémente le filtrage rapide et n'est pas requis lors de l'utilisation de données locales. Ce qui suit est fait uniquement à des fins de démonstration.

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. Il contient des propriétés pour chaque colonne triée. Les propriétés commencent à 0 et s'incrémentent au fur et à mesure que des colonnes supplémentaires sont 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.

Property	Description	Type
Field	Le champ à trier.	String
Sort	La direction dans laquelle trier le champ.	asc, desc

Contenu détaillé

Vous pouvez utiliser le gestionnaire d'événements -LoadDetailContent pour afficher des informations supplémentaires sur la ligne que vous développez. Les informations sur la ligne actuelle sont disponibles 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 sur 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 CPU. 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 cmdlet 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 prennent en charge l'édition en spécifiant le gestionnaire d'événements -OnEdit. Les nouvelles données de la ligne seront fournies sous la forme $EventData. Vous pouvez choisir de retourner des informations de ligne mises à jour (par exemple, en ajustant ce que l'utilisateur a saisi) et de les retourner depuis le gestionnaire d'événements. Si vous ne retournez rien, la ligne reflétera ce que l'utilisateur a saisi.

$EventData a le format suivant.

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

Assurez-vous de fournir la propriété editable à chaque colonne que vous souhaitez rendre modifiable par l'utilisateur.

$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 sur les lignes à sélectionner. La sélection de lignes nécessite un identifiant déterministe pour les lignes de données fournies. Dans l'exemple ci-dessous, vous verrez que chaque ligne possède un identifiant spécifique.

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énements -OnSelectionChange ou en récupérant les identifiants de lignes 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énements -OnExport. $EventData sera le même objet de contexte utilisé pour -LoadRows. Vous devez 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

Lors de l'utilisation d'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 allons créer 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 allons interroger 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