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

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

Package

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

サンプル アプリ

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 インスタンスになります。
• OverscanCount: スクロール中のレンダリング頻度を減らすために、可視領域の前後にレンダリングする追加項目の数を定義します。 値を大きくすると、画面外にレンダリングする項目が多くなることでスクロールのスムーズさが向上しますが、値が大きいほど初期読み込み時間が長くなる可能性もあります。 データ セットのサイズとユーザー エクスペリエンスの要件に基づいてバランスを取ることをお勧めします。 既定値は 3 です。 Virtualize を使用する場合のみ使用できます。
• Pagination: 必要に応じて、この TGridItem インスタンスを PaginationState モデルにリンクし、グリッドでデータの現在のページのみをフェッチしてレンダリングするようにします。 これは通常、Paginator コンポーネントや、指定された PaginationState インスタンスを表示および更新する他の UI ロジックと組み合わせて使います。
• QuickGrid の子コンテンツ (RenderFragment) で、PropertyColumn<TGridItem,TProp> を指定します。これは、そのセルに値が表示される TGridItem 列を表します。
  • Property: この列のセルに表示される値を定義します。
  • Format: 必要に応じて、値の書式指定文字列を指定します。 Format を使う場合は、IFormattable を実装する TProp 型が必要になります。
  • Sortable: この列でデータを並べ替え可能にするかどうかを示します。 既定値は、列の型によって異なる場合があります。 たとえば、TemplateColumn<TGridItem> は、SortBy パラメーターが指定されている場合、既定で並べ替え可能です。
  • InitialSortDirection: IsDefaultSortColumn が true の場合に、並べ替えの方向を示します。
  • IsDefaultSortColumn: 既定でこの列を並べ替える必要があるかどうかを示します。
  • PlaceholderTemplate: 指定した場合、仮想化されたグリッドではこのテンプレートを使って、データが読み込まれていないセルをレンダリングします。
  • HeaderTemplate: この列のヘッダー セル用の、省略可能なテンプレート。 指定されない場合は、既定のヘッダー テンプレートには Title と、適用される並べ替えインジケーターとオプション ボタンが含まれます。
  • Title: 列のタイトル テキスト。 HeaderTemplate が使用されていない場合は、タイトルは自動的にレンダリングされます。

• 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 を使う場合は、IFormattable を実装する TProp 型が必要になります。
  • Sortable: この列でデータを並べ替え可能にするかどうかを示します。 既定値は、列の型によって異なる場合があります。 たとえば、TemplateColumn<TGridItem> は、SortBy パラメーターが指定されている場合、既定で並べ替え可能です。
  • InitialSortDirection: IsDefaultSortColumn が true の場合に、並べ替えの方向を示します。
  • IsDefaultSortColumn: 既定でこの列を並べ替える必要があるかどうかを示します。
  • PlaceholderTemplate: 指定した場合、仮想化されたグリッドではこのテンプレートを使って、データが読み込まれていないセルをレンダリングします。
  • HeaderTemplate: この列のヘッダー セル用の、省略可能なテンプレート。 指定されない場合は、既定のヘッダー テンプレートには Title と、適用される並べ替えインジケーターとオプション ボタンが含まれます。
  • Title: 列のタイトル テキスト。 HeaderTemplate が使用されていない場合は、タイトルは自動的にレンダリングされます。

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

コンポーネントでは、対話型サーバー レンダリング モード (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();
}

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

QuickGrid の使用を開始するには:

パッケージの プレリリース パッケージ参照を Microsoft.AspNetCore.Components.QuickGrid 追加します。 .NET CLI を使ってパッケージ参照を追加する場合は、dotnet add package コマンドの実行時に --prerelease オプションを含めます。

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

PromotionGrid.razor:

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

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

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 パッケージのパッケージ参照を追加して開始します。

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

builder.Services.AddQuickGridEntityFrameworkAdapter();