ASP.NET Core BlazorQuickGrid 组件

QuickGrid 组件是一个 Razor 组件，用于以表格格式快速高效地显示数据。 QuickGrid 为常见网格呈现方案提供简单方便的数据网格组件，并充当构建数据网格组件的参考体系结构和性能基线。 QuickGrid 进行了高度的优化，并使用高级技术实现最佳呈现性能。

程序包

为 Microsoft.AspNetCore.Components.QuickGrid 包添加包引用。

注意

有关将包添加到 .NET 应用的指南，请参阅包使用工作流（NuGet 文档）中“安装和管理包”下的文章。 在 NuGet.org 中确认正确的包版本。

示例应用

有关各种 QuickGrid 演示，请参阅面向 Blazor 示例应用的快速入门。 演示网站托管在 GitHub Pages 上。 由于使用社区维护的 BlazorWasmPrerendering.Build GitHub 项目进行静态预呈现，因此站点加载速度较快。

QuickGrid 实现

若要实现 QuickGrid 组件，请执行以下操作：

• 在 Razor 标记 (<QuickGrid>...</QuickGrid>) 中指定 QuickGrid 组件的标记。
• 为网格命名可查询数据源。 使用以下任一数据源：
  • Items：可以为 null 的 IQueryable<TGridItem>，其中 TGridItem 是网格中每一行表示的数据类型。
  • ItemsProvider：为网格提供数据的回调。
• Class：可选的 CSS 类名称。 如果已提供，则类名称将包含在呈现的表的 class 属性中。
• Theme：主题名称（默认值：default）。 这会影响哪些样式规则与表匹配。
• Virtualize：如果为 true，则网格会使用虚拟化呈现。 这通常与滚动结合使用，导致网格仅提取和呈现当前滚动视区周围的数据。 这可以极大地提高滚动浏览大型数据集时的性能。 如果使用 Virtualize，则应为 ItemSize 提供值，并且必须确保每一行以恒定的高度呈现。 通常，如果呈现的数据量较小或使用的是分页，最好不要使用 Virtualize。
• ItemSize：仅当使用 Virtualize 时才适用。 ItemSize 定义每一行的预期高度（以像素为单位），使虚拟化机制能够提取正确数量的项，以匹配显示大小并确保准确滚动。
• ItemKey：（可选）在呈现的每一行上为 @key 定义值。 通常，这用于为每个数据项指定唯一标识符，例如主键值。 这样，网格就可以根据唯一标识符保留行元素和数据项之间的关联，即使 TGridItem 实例被新副本替换（例如，在对基础数据存储执行新查询之后）也是如此。 如果未设置，则 @key 为 TGridItem 实例。
• Pagination：（可选）将此 TGridItem 实例与 PaginationState 模型链接，使网格仅提取并呈现数据的当前页。 这通常与 Paginator 组件或显示和更新提供的 PaginationState 实例的一些其他 UI 逻辑结合使用。
• 在 QuickGrid 子内容 (RenderFragment) 中，指定 PropertyColumn<TGridItem,TProp>，表示单元格显示值的 TGridItem 列：
  • Property：定义要在此列的单元格中显示的值。
  • Format：（可选）指定值的格式字符串。 使用 Format 需要 TProp 类型来实现 IFormattable。
  • Sortable：指示是否应按此列对数据进行排序。 默认值可能因列类型而异。 例如，如果指定了任何 TemplateColumn<TGridItem> 参数，则默认情况下可对 SortBy 进行排序。
  • InitialSortDirection：如果 IsDefaultSortColumn 为 true，则指示排序方向。
  • IsDefaultSortColumn：指示默认情况下是否应对此列进行排序。
  • PlaceholderTemplate：如果已指定，虚拟化网格使用此模板呈现尚未加载数据的单元格。

例如，添加以下组件以呈现网格。

该组件假定交互式服务器呈现模式（InteractiveServer）继承自父组件或全局应用到应用，从而启用交互式功能。 对于以下示例，唯一的交互式功能是可排序的列。

PromotionGrid.razor：

@page "/promotion-grid"
@using Microsoft.AspNetCore.Components.QuickGrid

<PageTitle>Promotion Grid</PageTitle>

<h1>Promotion Grid Example</h1>

<QuickGrid Items="@people">
    <PropertyColumn Property="@(p => p.PersonId)" Sortable="true" />
    <PropertyColumn Property="@(p => p.Name)" Sortable="true" />
    <PropertyColumn Property="@(p => p.PromotionDate)" Format="yyyy-MM-dd" Sortable="true" />
</QuickGrid>

@code {
    private record Person(int PersonId, string Name, DateOnly PromotionDate);

    private IQueryable<Person> people = new[]
    {
        new Person(10895, "Jean Martin", new DateOnly(1985, 3, 16)),
        new Person(10944, "António Langa", new DateOnly(1991, 12, 1)),
        new Person(11203, "Julie Smith", new DateOnly(1958, 10, 10)),
        new Person(11205, "Nur Sari", new DateOnly(1922, 4, 27)),
        new Person(11898, "Jose Hernandez", new DateOnly(2011, 5, 3)),
        new Person(12130, "Kenji Sato", new DateOnly(2004, 1, 9)),
    }.AsQueryable();
}

在浏览器中的相对路径 /promotion-grid 处访问组件。

目前没有使用完全成熟的商业网格倾向于提供的功能扩展 QuickGrid 的计划，例如分层行、拖动以重新排序列或类似于 Excel 的范围选择。 如果需要不希望自行开发的高级功能，请继续使用第三方网格。

自定义属性和样式

QuickGrid 还支持将自定义属性和样式类传递给呈现的表元素：

<QuickGrid Items="..." custom-attribute="value" class="custom-class">

Entity Framework Core (EF Core) 数据源

EF Core 的 DbContext 为数据库中的每个表都提供了一个 DbSet<TEntity> 属性。 将属性提供给 Items 参数。

以下示例使用 PeopleDbSet<TEntity>（表）作为数据源：

@inject ApplicationDbContext AppDbContext

<QuickGrid Items="@AppDbContext.People">
    ...
</QuickGrid>

还可以使用任何 EF 支持的 LINQ 运算符来筛选数据，然后再将其传递给 Items 参数。

以下示例按类别 ID 筛选文档：

<QuickGrid Items="@AppDbContext.Documents.Where(d => d.CategoryId == categoryId)">
    ...
</QuickGrid>

QuickGrid 可识别 EF 提供的 IQueryable 实例，并知道如何异步解析查询以提高效率。

首先，为 Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter NuGet 包添加包引用。

注意

有关将包添加到 .NET 应用的指南，请参阅包使用工作流（NuGet 文档）中“安装和管理包”下的文章。 在 NuGet.org 中确认正确的包版本。

调用 Program 文件中服务集合上的 AddQuickGridEntityFrameworkAdapter，以注册 EF 感知 IAsyncQueryExecutor 实现：

builder.Services.AddQuickGridEntityFrameworkAdapter();

远程数据

在 Blazor WebAssembly 应用中，从服务器上的基于 JSON 的 Web API 提取数据是一个常见要求。 若要仅提取当前页/数据视区所需的数据，并在服务器上应用排序或筛选规则，请使用 ItemsProvider 参数。

在服务器端 Blazor 应用中，如果需要应用来查询外部终结点，或者在 IQueryable 无法满足要求的其他情况下，也可以使用 ItemsProvider。

提供与 GridItemsProvider<TGridItem> 委托类型匹配的回调，其中 TGridItem 是网格中显示的数据类型。 该回调被赋予一个 GridItemsProviderRequest<TGridItem> 类型的参数，它指定了要返回的数据的起始索引、最大行计数和排序顺序。 除了返回匹配项之外，分页和虚拟化还需要总项计数 (totalItemCount) 才能正常运行。

以下示例从公开的 OpenFDA Food Enforcement 数据库获取数据。

GridItemsProvider<TGridItem> 将 GridItemsProviderRequest<TGridItem> 转换为针对 OpenFDA 数据库的查询。 查询参数转换为外部 JSON API 支持的特定 URL 格式。 只能通过外部 API 支持的排序和筛选来执行排序和筛选。 OpenFDA 终结点不支持排序，因此没有任何列标记为可排序。 但是，它确实支持跳过记录（skip 参数）和限制返回记录的数量（limit 参数），以便组件可以启用虚拟化，并快速滚动浏览数万条记录。

FoodRecalls.razor：

@page "/food-recalls"
@inject HttpClient Http
@inject NavigationManager NavManager

<PageTitle>Food Recalls</PageTitle>

<h1>OpenFDA Food Recalls</h1>

<div class="grid" tabindex="-1">
    <QuickGrid ItemsProvider="@foodRecallProvider" Virtualize="true">
        <PropertyColumn Title="ID" Property="@(c => c.Event_Id)" />
        <PropertyColumn Property="@(c => c.State)" />
        <PropertyColumn Property="@(c => c.City)" />
        <PropertyColumn Title="Company" Property="@(c => c.Recalling_Firm)" />
        <PropertyColumn Property="@(c => c.Status)" />
    </QuickGrid>
</div>

<p>Total: <strong>@numResults results found</strong></p>

@code {
    GridItemsProvider<FoodRecall>? foodRecallProvider;
    int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = NavManager.GetUriWithQueryParameters(
                "https://api.fda.gov/food/enforcement.json", 
                new Dictionary<string, object?>
            {
                { "skip", req.StartIndex },
                { "limit", req.Count },
            });

            var response = await Http.GetFromJsonAsync<FoodRecallQueryResult>(
                url, req.CancellationToken);

            return GridItemsProviderResult.From(
                items: response!.Results,
                totalItemCount: response!.Meta.Results.Total);
        };

        numResults = (await Http.GetFromJsonAsync<FoodRecallQueryResult>(
            "https://api.fda.gov/food/enforcement.json"))!.Meta.Results.Total;
    }
}

有关调用 Web API 的详细信息，请参阅在 ASP.NET Core Blazor 应用中调用 Web API。

QuickGrid 基架

Visual Studio Preview 中的预览版 QuickGrid 基架可搭建 Razor 组件，用 QuickGrid 显示数据库中的数据。

若要使用基架，请在解决方案资源管理器中右键单击项目，然后选择“添加”>“新建基架项”。 打开“已安装”>“通用”>“Razor 组件”。 选择“使用 Entity Framework (CRUD) 的 Razor 组件”。

基架基于 Entity Framework Core 数据模型生成基本的创建、读取、更新和删除 (CRUD) 页。 可以搭建单个页面或所有 CRUD 页面。 选择模型类和 DbContext，根据需要创建新的 DbContext。

搭建的 Razor 组件会添加到以模型类命名的生成的文件夹中项目的 Pages 文件夹内。 生成的 Index 组件使用 QuickGrid 显示数据。 根据需要自定义生成的组件，并使交互性能够利用交互式功能，例如排序和筛选。

基架生成的组件需要服务器端呈现 (SSR)，因此在 WebAssembly 上运行时不支持它们。