ASP.NET Core BlazorQuickGrid コンポーネント

QuickGrid コンポーネントは、データを表形式ですばやく効率的に表示するための Razor コンポーネントです。 QuickGrid では、グリッドをレンダリングする一般的なシナリオに向けたシンプルで便利なデータ グリッド コンポーネントが提供されます。データ グリッド コンポーネントを構築するための参照アーキテクチャとパフォーマンス ベースラインとして機能します。 QuickGrid は高度に最適化されており、高度な手法を使って最適なレンダリング パフォーマンスを実現します。

Package

Microsoft.AspNetCore.Components.QuickGrid パッケージのパッケージ参照を追加します。

サンプル アプリ

QuickGrid のさまざまなデモについては、QuickGrid for Blazor のサンプル アプリに関するページを参照してください。 このデモ サイトは GitHub Pages でホストされています。 コミュニティによって管理される BlazorWasmPrerendering.Build GitHub プロジェクトを使用した静的プリレンダリングにより、このサイトは高速に読み込まれます。

QuickGrid実装

QuickGrid コンポーネントを実装するには:

たとえば、次のコンポーネントを追加してグリッドをレンダリングします。

Blazor Web App でページングや並べ替えなどの対話型機能を有効にする場合は、QuickGrid コンポーネントで対話型レンダリング モードを採用する必要があります。

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();
}

@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 にあるコンポーネントにアクセスします。

現時点では、本格的な商用グリッドが提供するような機能、たとえば階層型の行、ドラッグして並べ替える列、Excel に似た範囲の選択などによって、QuickGrid を拡張する計画はありません。 独自に開発する予定のない高度な機能が必要な場合は、引き続きサードパーティ製のグリッドをお使いください。

列で並べ替え

QuickGrid コンポーネントでは、列ごとに項目を並べ替えることができます。 Blazor Web App では、並べ替えは、コンポーネントが対話型レンダリング モードを採用する必要があります。

PropertyColumn<TGridItem,TProp> タグに Sortable="true" (Sortable) を追加します。

<PropertyColumn Property="..." Sortable="true" />

実行中のアプリで、レンダリングされた列のタイトルを選択して QuickGrid 列を並べ替えます。

Paginator コンポーネントを含むページ項目

QuickGrid コンポーネントは、データ ソースからのデータをページングできます。 Blazor Web App のページングでは、コンポーネントが対話型レンダリング モードを採用する必要があります。

コンポーネントの @code ブロックに PaginationState インスタンスを追加します。 ページごとに表示する項目の数に、ItemsPerPage を設定します。 次の例では、インスタンスには pagination という名前が付けられ、ページごとに 10 個の項目が設定されています。

PaginationState pagination = new PaginationState { ItemsPerPage = 10 };

QuickGrid コンポーネントの Pagination プロパティを pagination に設定します。

<QuickGrid Items="..." Pagination="pagination">

改ページ位置の自動修正 UI を提供するには、QuickGrid コンポーネントの上または下の Paginator コンポーネントを追加します。 Paginator.State を pagination に設定します。

<Paginator State="pagination" />

実行中のアプリで、レンダリングされた Paginator コンポーネントを使用して項目をページングします。

カスタム属性とスタイル

QuickGrid では、レンダリングされたテーブル要素にカスタム属性とスタイル クラス (Class) を渡すことがサポートされています。

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

Entity Framework Core (EF Core) データ ソース

ファクトリ パターンを使用して、QuickGrid コンポーネントにデータを提供する EF Core データベース コンテキストを解決します。 ファクトリ パターンが推奨される理由の詳細については、「ASP.NET Core Blazor と Entity Framework Core (EF Core)」を参照してください。

データベース コンテキスト ファクトリ (IDbContextFactory<TContext>) は @inject ディレクティブを使用してコンポーネントに挿入されます。 このファクトリ アプローチではデータベース コンテキストの破棄が必要であるため、コンポーネントは @implements ディレクティブを使用して IAsyncDisposable インターフェイスを実装します。 QuickGrid コンポーネントのアイテム プロバイダーは、挿入されたデータベース コンテキスト ファクトリの作成されたデータベース コンテキスト (CreateDbContext) から取得された DbSet<T> です。

QuickGrid は、EF 提供の IQueryable インスタンスを認識し、効率を高めるためにクエリを非同期的に解決する方法を認識しています。

Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter NuGet パッケージのパッケージ リファレンスを追加します。

Program ファイルのサービス コレクションで AddQuickGridEntityFrameworkAdapter を呼び出し、IAsyncQueryExecutor の EF に対応した実装を登録します。

builder.Services.AddQuickGridEntityFrameworkAdapter();

次の例では、QuickGrid コンポーネントのデータ ソースとして、AppDbContext データベース コンテキスト (context) の ExampleTable DbSet<TEntity> (テーブル) を使用します。

@using Microsoft.AspNetCore.Components.QuickGrid
@using Microsoft.EntityFrameworkCore
@implements IAsyncDisposable
@inject IDbContextFactory<AppDbContext> DbFactory

...

<QuickGrid ... Items="context.ExampleTable" ...>
    ...
</QuickGrid>

@code {
    private AppDbContext context = default!;

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

上の例のコード ブロック (@code) 内において:

• context フィールドはデータベース コンテキストを保持し、AppDbContext として型付けされます。
• OnInitialized ライフサイクル メソッドは、挿入されたファクトリ (DbFactory) からの新しいデータベース コンテキスト (CreateDbContext) を context フィールドに割り当てます。
• 非同期の DisposeAsync メソッドは、コンポーネントが破棄されるときにデータベース コンテキストを破棄します。

EF でサポートされている LINQ 演算子を使用して、Items パラメーターに渡す前にデータをフィルター処理することもできます。

次の例は、検索ボックスに入力された映画タイトルで映画をフィルター処理します。 データベース コンテキストは BlazorWebAppMoviesContext であり、モデルは Movie です。 映画の Title プロパティは、フィルター操作のために使用されます。

@using Microsoft.AspNetCore.Components.QuickGrid
@using Microsoft.EntityFrameworkCore
@implements IAsyncDisposable
@inject IDbContextFactory<BlazorWebAppMoviesContext> DbFactory

...

<p>
    <input type="search" @bind="titleFilter" @bind:event="oninput" />
</p>

<QuickGrid ... Items="FilteredMovies" ...>
    ...
</QuickGrid>

@code {
    private string titleFilter = string.Empty;
    private BlazorWebAppMoviesContext context = default!;

    protected override void OnInitialized()
    {
        context = DbFactory.CreateDbContext();
    }

    private IQueryable<Movie> FilteredMovies => 
        context.Movie.Where(m => m.Title!.Contains(titleFilter));

    public async ValueTask DisposeAsync() => await context.DisposeAsync();
}

表示名のサポート

列のタイトルは、PropertyColumn<TGridItem,TProp> のタグ内で ColumnBase<TGridItem>.Title を使用して割り当てることができます。 次の映画の例では、列の映画公開日データに合わせて、この列に "Release Date" という名前が付けられています。

<PropertyColumn Property="movie => movie.ReleaseDate" Title="Release Date" />

ただし、列のタイトル (名前) の管理はバインドされたモデル プロパティから行うほうが一般的に、アプリの保守のためには良い選択肢です。 モデルによってプロパティの表示名を制御するには、[Display] 属性を使用します。 次の例では、モデルによって映画公開日の表示名 "Release Date" が ReleaseDate プロパティに対して指定されています。

[Display(Name = "Release Date")]
public DateTime ReleaseDate { get; set; }

QuickGrid コンポーネントが DisplayAttribute.Name を使用できるようにするには、次のように PropertyColumn<TGridItem,TProp> をそのコンポーネント内または別のクラス内でサブクラス化します。

public class DisplayNameColumn<TGridItem, TProp> : PropertyColumn<TGridItem, TProp>
{
    protected override void OnParametersSet()
    {
        if (Title is null && Property.Body is MemberExpression memberExpression)
        {
            var memberInfo = memberExpression.Member;
            Title = 
                memberInfo.GetCustomAttribute<DisplayNameAttribute>().DisplayName ??
                memberInfo.GetCustomAttribute<DisplayAttribute>().Name ??
                memberInfo.Name;
        }

        base.OnParametersSet();
    }
}

このサブクラスを QuickGrid コンポーネント内で使用します。 次の例では、前述の DisplayNameColumn が使用されています。 名前 "Release Date" というはモデル内の [Display] 属性によって提供されるため、Title を指定する必要はありません。

<DisplayNameColumn Property="movie => movie.ReleaseDate" />

[DisplayName] 属性もサポートされます。

[DisplayName("Release Date")]
public DateTime ReleaseDate { get; set; }

ただし、[Display] 属性が推奨されていますが、その理由は追加のプロパティを使用できるようになることです。 たとえば、[Display] 属性では、ローカライズ用のリソースの種類を割り当てることが可能です。

リモート データ

Blazor WebAssembly アプリでは、サーバー上の JSON ベースの Web API からデータをフェッチすることが一般的な要件です。 データの現在のページまたはビューポートに必要なデータのみをフェッチし、サーバーに並べ替えまたはフィルター処理ルールを適用するには、ItemsProvider パラメーターを使用します。

ItemsProvider は、アプリが外部エンドポイントのクエリを実行する必要がある場合や、要件が IQueryable でカバーされていない場合に、サーバー側の Blazor アプリでも使用できます。

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 Navigation

<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 {
    private GridItemsProvider<FoodRecall>? foodRecallProvider;
    private int numResults;

    protected override async Task OnInitializedAsync()
    {
        foodRecallProvider = async req =>
        {
            var url = Navigation.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 スキャフォールディング

QuickGrid スキャフォールディングは Razor コンポーネントを QuickGrid でスキャフォールディングし、データベースからのデータを表示します。

スキャフォールディングによって、Entity Framework Core データ モデルに基づいた基本的な作成、読み取り、更新、削除 (CRUD) ページが生成されます。 個々のページまたはすべての CRUD ページをスキャフォールディングできます。 モデル クラスと DbContext を選択し、必要に応じて DbContext を作成します (省略可能)。

スキャフォールディングされた Razor コンポーネントは、モデル クラスに基づく名前で生成されたフォルダー内にあるプロジェクト フォルダーに追加されます。 生成された Index コンポーネントは、QuickGrid コンポーネントを使用してデータを表示します。 生成されたコンポーネントを必要に応じてカスタマイズし、対話機能を有効にして、ページング、並べ替え、フィルター処理などの対話型機能を利用できるようにします。

スキャフォールディングによって生成されるコンポーネントにはサーバー側レンダリング (SSR) が必要であるため、WebAssembly で実行する場合はサポートされません。

dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.SQLite
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Microsoft.AspNetCore.Components.QuickGrid
dotnet add package Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter

dotnet aspnet-codegenerator blazor CRUD -dbProvider {PROVIDER} -dc {DB CONTEXT CLASS} -m {MODEL} -outDir {PATH}

dotnet aspnet-codegenerator blazor -h

dotnet tool install --global dotnet-aspnet-codegenerator
dotnet tool install --global dotnet-ef
dotnet add package Microsoft.EntityFrameworkCore.SQLite
dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Microsoft.AspNetCore.Components.QuickGrid
dotnet add package Microsoft.AspNetCore.Components.QuickGrid.EntityFrameworkAdapter

dotnet aspnet-codegenerator blazor CRUD -dbProvider {PROVIDER} -dc {DB CONTEXT CLASS} -m {MODEL} -outDir {PATH}

dotnet aspnet-codegenerator blazor -h