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

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

Package

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

Note

.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 コンポーネントや、指定された PaginationState インスタンスを表示および更新する他の UI ロジックと組み合わせて使います。
• QuickGrid の子コンテンツ (RenderFragment) で、PropertyColumn<TGridItem,TProp> を指定します。これは、そのセルに値が表示される TGridItem 列を表します。
  • Property: この列のセルに表示される値を定義します。
  • Format: 必要に応じて、値の書式指定文字列を指定します。 Format を使う場合は、IFormattable を実装する TProp 型が必要になります。
  • 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();
}

クエリ可能なデータ ソースとして Entity Framework Core で IQueryable を使う例については、ASP.NET Core Basic Test App の SampleQuickGridComponent コンポーネント (dotnet/aspnetcore GitHub リポジトリ) を参照してください。

Note

通常、.NET 参照ソースへのドキュメント リンクを使用すると、リポジトリの既定のブランチが読み込まれます。このブランチは、.NET の次回リリースに向けて行われている現在の開発を表します。 特定のリリースのタグを選択するには、[Switch branches or tags](ブランチまたはタグの切り替え) ドロップダウン リストを使います。 詳細については、「ASP.NET Core ソース コードのバージョン タグを選択する方法」 (dotnet/AspNetCore.Docs #26205) を参照してください。

データ ソースとして Entity Framework (EF) Core を使うには:

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

  Note

  .NET アプリへのパッケージの追加に関するガイダンスについては、「パッケージ利用のワークフロー」 (NuGet ドキュメント) の "パッケージのインストールと管理" に関する記事を参照してください。 NuGet.org で正しいパッケージ バージョンを確認します。

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

  builder.Services.AddQuickGridEntityFrameworkAdapter();
  

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

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

ブラウザーで相対パス /promotion-grid にあるコンポーネントにアクセスします。

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

QuickGrid スキャフォールディング

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

スキャフォールディングを使用するには、ソリューション エクスプローラーでプロジェクトを右クリックし、[追加]>[新規スキャフォールディング アイテム] を選択します。 [インストール済み]>[共通]>[Razor コンポーネント] を選択します。 [Razor Components using Entity Framework (CRUD)] (Entity Framework を使用する Razor コンポーネント (CRUD)) を選択します。

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

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

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