ASP.NET Core BlazorQuickGrid 元件

QuickGrid 元件是 Razor 元件，可快速且有效率地以表格格式顯示資料。 QuickGrid 為常見的格線轉譯案例提供簡單且方便的資料格元件，並作為建置資料格線元件的參考架構和效能基準。 QuickGrid 已高度最佳化，並使用進階技巧來達到最佳轉譯效能。

套件

新增 Microsoft.AspNetCore.Components.QuickGrid 套件的套件參考。

注意

如需將套件新增至 .NET 應用程式的指引，請參閱在套件取用工作流程 (NuGet 文件) 的安裝及管理套件底下的文章。 在 NuGet.org 確認正確的套件版本。

範例應用程式

如需各種 QuickGrid 示範，請參閱 QuickGrid for 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 元件或其他 UI 邏輯搭配使用，以顯示和更新所提供的 PaginationState 執行個體。
• 在 QuickGrid 子系內容 (RenderFragment) 中，指定 PropertyColumn<TGridItem,TProp>，其代表儲存格顯示值的 TGridItem 資料行：
  • Property：定義要顯示在此資料行儲存格中的值。
  • Format：選擇性地指定此值的格式字串。 使用 Format 需要 TProp 型別才能實作 IFormattable。
  • Sortable：指出資料是否可依這個資料行排序。 預設值可能根據資料行類型而有所不同。 例如，如果指定了任何 SortBy 參數，TemplateColumn<TGridItem> 預設可排序。
  • 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 參數。

下列範例依類別識別碼篩選文件：

<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 參數。

如果查詢外部端點，或是 IQueryable 未涵蓋需求的其他案例需要應用程式，也可以在伺服器端 Blazor 應用程式使用 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 Scaffolder

Visual Studio 中的 QuickGrid Scaffolder 會使用 QuickGrid 來建立 Razor 元件的 Scaffolding 框架以顯示資料庫中的資料。

若要使用 Scaffolder，請以滑鼠右鍵按一下 [方案總管] 中的專案，然後選取 [新增]>[新增 Scaffolded 項目]。 開啟 [已安裝]>[一般]>[Razor 元件]。 選取 [使用 Entity Framework (CRUD) 的 Razor 元件]。

此 Scaffolder 會根據 Entity Framework Core 資料模型來產生基本的建立、讀取、更新和刪除 (CRUD) 頁面。 您可以建立個別頁面或所有 CRUD 頁面的 Scaffolding 框架。 您可以選取模型類別和 DbContext，視需要選擇性地建立新的 DbContext。

此 Scaffolded Razor 元件會新增至專案的 Pages 資料夾中 (該資料夾位於以模型類別命名的產生資料夾中)。 產生的 Index 元件會使用 QuickGrid 來顯示資料。 視需要自訂產生的元件，並啟用互動功能以利用互動式功能，例如排序和篩選。

此 Scaffolder 所產生的元件需要伺服器端轉譯 (SSR)，因此在 WebAssembly 上執行時不支援它們。