syncfusion-blazor-datagrid

---

Syncfusion Blazor DataGrid の実装

Syncfusion Blazor DataGrid（SfGrid<TValue>）は、表形式データの表示と操作に対応した、高性能で豊富な機能を備えるコンポーネントです。データバインディング、並べ替え、フィルタリング、グループ化、ページング、編集、選択、集計、エクスポート、仮想スクロール／無限スクロール、テンプレートなどに対応しています。

NuGet: Syncfusion.Blazor.Grid + Syncfusion.Blazor.Themes
名前空間: Syncfusion.Blazor.Grids

このスキルを使用する場面

以下が必要な場合に、このスキルを使用してください。

• Blazor Server、WebAssembly、Web App、または MAUI で DataGrid をセットアップして構成する
• ローカルデータまたはリモートデータ（OData、HTTP、SfDataManager）をバインドする
• 列を構成する（型、書式、テンプレート、固定、並べ替え、サイズ変更、列選択）
• 並べ替え、フィルタリング（FilterBar／Menu／Excel／CheckBox）、または検索を実装する
• 遅延読み込みまたはキャプションテンプレートを使用してグループ化を有効にする
• カスタムテンプレートまたは SfPager を使用してページングを構成する
• 大規模なデータセット向けに仮想スクロールや無限スクロールをセットアップする
• 検証を伴う編集（Normal／Dialog／Batch／Command 列）を実装する
• プログラムからの制御を含む選択（行、セル、チェックボックス）を構成する
• クリップボードへのコピー、AutoFill、または貼り付け機能を使用する
• 集計（フッター、グループ、キャプション、リアクティブ）を追加する
• 行／列テンプレート、詳細テンプレート、行のドラッグ＆ドロップを使用する
• ツールバー、コンテキストメニュー、列メニュー、列選択を構成する
• データを Excel または PDF にエクスポートする
• 印刷機能を管理する
• パフォーマンスを最適化する（SetRowDataAsync、PreventRender）
• DataGrid のイベントを処理する
• 状態の永続化を管理する（EnablePersistence）
• スタイルと外観をカスタマイズする
• モバイル／レスポンシブレイアウト向けにアダプティブ UI を有効にする

🔒 必須の主要ルール

これらのルールは、このスキルがどのように動作しなければならないかを定めます。必須事項であり、厳守してください。

1. 目的と責任

あなたの責任は、自然言語によるユーザーのあらゆるリクエストを解釈し、Syncfusion Blazor DataGrid のサポートされているすべての側面について、次の情報を提供することです。

• 正確な情報
• 完全な情報
• 検証済みの情報

対象には以下が含まれます。

• パブリック API
• プロパティ
• イベント
• 機能
• 動作

2. 正確性と API への準拠

このスキルは、以下を守らなければなりません。

• Syncfusion DataGrid で公式にサポートされている機能のみを使用する。
• API、メソッド、プロパティ、イベント、動作、将来の機能を決してでっち上げない。
• サポートされていないコードサンプルや仮定に基づくコードサンプルを決して提示しない。
• 常に Syncfusion コンポーネントの公式な設計パターンに従う。

機能がサポートされていない場合は、以下のようにしてください。

• 制限事項を明確に伝える。
• 可能であれば、サポートされている代替案を提案する。

3. 自然言語によるリクエストの解釈

ユーザーのリクエストが不完全な場合は、以下のようにしてください。

• Grid の公式なベストプラクティスに基づき、妥当な前提を推測する。
• 不足している情報を、正確で関連性のある内容で補う。
• 必要不可欠な場合に限り、確認を求める。

4. 回答の品質要件

すべての回答は、以下を満たさなければなりません。

• 技術的に正確である
• 完全で、構成が明確である
• 必要な依存関係と構成に関する注意事項を含む
• 文書化された Syncfusion API の実際の動作に従う
• 矛盾や曖昧さを避ける

5. サポートされていないリクエストへの対応

ユーザーがサポートされていない機能を求めた場合は、以下のようにしてください。

• その機能がサポートされていないことを明示する
• 公式の代替案、または有効な回避策を提案する
• 実現不可能な機能を決して模倣したり、でっち上げたりしない

6. 設計パターンの適用

このスキルは、以下を含む Syncfusion の公式パターンに従わなければなりません。

• 正しいコンポーネント構造（SfGrid、GridColumn、GridEditSettings など）
• 適切な非同期イベントと API の使用
• 有効な構成プロパティと列挙値
• サポートされているデータバインディング方式
• 実際のイベントパターンとイベント名

7. 品質、完全性、信頼性

このスキルは、以下を守らなければなりません。

• 検証済みで実際に利用できる Grid の機能のみを使用する
• すぐに実装でき、実行に移せるガイダンスを提供する
• ユーザーが推測に頼らず実行できるよう、明確に説明する
• すっきりとして読みやすく、プロフェッショナルな形式を保つ

8. ハルシネーション防止のための安全策

スキルは次のことをしてはいけません。

• 存在しない API や動作をでっち上げる
• サポートされていないモード、機能、設定を提案する
• 不正確、誤解を招く、または検証不可能なコードを提示する
• 文書化されていない内部動作を説明する

不明な場合は、次のいずれかを行ってください。

• 明確化を求める または
• 制限事項を明確に示す

9. イベント名の検証要件

重要： コード例を提示する前に、イベント名を references/events.md で必ず検証してください。すべてのグリッドイベントは <GridEvents> コンポーネント内で定義する必要があります。

よくある間違い：

• ❌ OnSortChange - 存在しません。代わりに Sorting、Sorted を使用してください
• ❌ OnFilterChange - 存在しません。代わりに Filtering、Filtered を使用してください
• ❌ OnPageChange - 存在しません。代わりに PageChanging、PageChanged を使用してください
• ❌ OnGroupChange - 存在しません。代わりに Grouping、Grouped を使用してください

ルール： 次の項目は、必ず references/events.md と照合してください。

• 正確なイベント名（大文字と小文字を区別）
• イベント引数の型
• イベントがキャンセル可能かどうか
• イベントが発生するタイミング（操作の前／後）

イベントコードを提示する前の確認事項：

1. イベント名が references/events.md に存在するか確認します
2. 正しい EventArgs の型を確認します
3. Cancelable の状態（✅ または ❌）を確認します
4. Syncfusion の公式ドキュメントで検証します
5. 命名規則（例：On 接頭辞、Change 接尾辞）を決めつけないでください

---

グリッドイベントに関する厳格なルール

1. イベントハンドラーは <GridEvents> コンポーネント内に置く必要があります

• ✅ すべてのイベントハンドラーを <GridEvents TValue="YourType"> 内で定義します
• ✅ 正確なイベント名をプロパティとして使用します（例：DataBound、RowSelecting、Grouped）
• ❌ <SfGrid> で @onEventName 構文を使用しないでください
• ❌ ルート要素にイベントハンドラーを定義しないでください

2. イベントハンドラーのシグネチャを正しく指定する

• ✅ イベントハンドラーには async Task を使用します
• ✅ イベントハンドラーには、特定のパラメーター型が必要な場合があります（例：GridEventArgs、RowSelectEventArgs）
• ✅ パラメーターを取らないイベントもあります（例：DataBound()、Created()）
• ❌ 非同期処理に同期 void メソッドを使用しないでください

3. API メソッドの呼び出しをライフサイクルイベント内で行わない

• ❌ OnInitialized() で API メソッドを呼び出さないでください
• ❌ OnAfterRenderAsync() で API メソッドを呼び出さないでください
• ❌ OnParametersSet() で API メソッドを呼び出さないでください
• ✅ API メソッドは、ユーザー操作（ボタンクリック、ドロップダウンの変更など）に応じて呼び出す場合に限ります
• ✅ API メソッドは GridEvents ハンドラー内で呼び出せます

4. 非同期／待機パターンを使用する

• ✅ 非同期 API メソッドでは必ず await を使用します
• ✅ イベントハンドラーは async Task として定義します
• ✅ コードブロックのメソッドは async Task として定義します
• ❌ 非同期処理に同期メソッド呼び出しを使用しないでください

5. API 呼び出しにはグリッド参照が必要です

• ✅ @ref="Grid" を使用して Grid インスタンスを取得します
• ✅ 参照を使用して API メソッドを呼び出します（例：await Grid.GroupColumnAsync()）
• ❌ 参照なしでメソッドを呼び出そうとしないでください

6. イベントの型は GridEvents の TValue と一致させる必要があります

• ✅ データモデルに合わせて TValue="YourDataType" を設定します
• ✅ すべてのイベントハンドラーで、このモデルに基づく適切な型が使用されます
• ❌ TValue に汎用型や誤った型を使用しないでください

---

ナビゲーションガイド

セットアップと使い始め方

📄 参照： references/getting-started.md

• NuGet のインストール、_Imports.razor、Program.cs、テーマ／スクリプトの設定、基本的なグリッド

📄 参照： references/getting-started-app-types.md

• Server App、Web App（Auto/WASM）、MAUI の各バリエーション

データ

📄 参照： references/data-binding.md

• ローカルデータ（List、ExpandoObject、DynamicObject、DataTable、ObservableCollection）

アダプターへの接続（リモートデータ）

📄 参照： references/odatav4-adaptor.md

• OData V4 サービスのセットアップ、ODataConventionModelBuilder、[EnableQuery]、$filter/$orderby/$skip/$top の自動処理、PATCH/DELETE による CRUD

📄 参照： references/web-api-adaptor.md

• { Items, Count } 形式のレスポンスを使用する Web API、$filter/$orderby/$skip/$top の QueryString の手動解析、GET/POST/PUT/DELETE による CRUD
• セキュリティに関する注意： SfDataManager.Url をユーザーが任意に指定した URL にバインドしないでください。オペレーターが設定する文字列変数（例：構成の ALLOWED_API_URL から DataApiUrl を読み込み、Url="@DataApiUrl" とする）、内部プロキシ／ゲートウェイ、フィールド／オペレーターの許可リスト、サーバー側での検証／サニタイズを使用してください。例については、references/web-api-adaptor.md の Security Considerations を参照してください。

📄 参照： references/url-adaptor.md

• { result, count } 形式のレスポンスを使用するカスタム API、DataManagerRequest の POST 本文、DataOperations ヘルパー、InsertUrl/UpdateUrl/RemoveUrl/CrudUrl/BatchUrl
• セキュリティに関する注意： 構成に基づく URL 変数（例：構成の ALLOWED_API_URL から DataApiUrl を読み込み、Url="@DataApiUrl" とする）を使用し、ユーザー指定のエンドポイントは避け、サードパーティへのリクエストは内部プロキシ／ゲートウェイ経由で送信してください。例と構成スニペットについては、references/url-adaptor.md を参照してください。

📄 参照： references/custom-adaptor.md

• DataAdaptor 抽象クラス、Read/Insert/Update/Remove/BatchUpdate のオーバーライド、サービスのインジェクション、アダプターをコンポーネントとして使用、Query.AddParams によるカスタムパラメーター
• セキュリティに関する注意： CustomAdaptor を実装する際は、dm.Params やユーザー指定のエンドポイントを信頼しないでください。オペレーターが設定するエンドポイントを使用し、dm.Params を検証し、フィールド／オペレーターの許可リストを適用し、サードパーティへの呼び出しはプロキシ経由で送信してください。例については、references/custom-adaptor.md の Security Considerations を参照してください。

列

📄 参照： references/columns.md

• ColumnType、Format、TextAlign、固定、並べ替え、サイズ変更、列選択、複数段ヘッダー、列メニュー、外部キー

📄 参照： references/cell.md

• QueryCellInfo、CustomAttributes、ClipMode、GridLines、ツールチップ

並べ替え、フィルタリング、検索

📄 参照： references/sorting.md

• AllowSorting、複数列の並べ替え、SortColumnAsync、ClearSortingAsync

📄 参照： references/filtering.md

• AllowFiltering、FilterType（FilterBar/Menu/Excel/CheckBox）、オペレーター、FilterByColumnAsync

📄 参照： references/searching.md

• ツールバー検索、SearchAsync、GridSearchSettings

グループ化とページング

📄 参照： references/grouping.md

• AllowGrouping、遅延読み込みによるグループ化、CaptionTemplate、プログラムによるグループ化／グループ解除

📄 参照： references/paging.md

• AllowPaging、GridPageSettings、ページャーテンプレート、GoToPageAsync

スクロール

📄 参照： references/scrolling.md

• Height/Width、固定ヘッダー、ScrollIntoViewAsync

📄 参照： references/virtual-scrolling.md

• EnableVirtualization、EnableColumnVirtualization、OverscanCount、制限事項

📄 参照： references/infinite-scrolling.md

• EnableInfiniteScrolling、GridInfiniteScrollSettings、キャッシュモード、制限事項

編集

📄 参照： references/editing.md

• GridEditSettings、EditMode（Normal／Dialog／Batch／CommandColumn）、ValidationRules、EditType、EditTemplate、CRUD メソッド

参照： references/editing-patterns.md

• 条件に基づいて編集をキャンセルする、特定の行の編集を無効にする
• イベントを介して新規／編集済みの項目を渡す、列の既定値、新しい行の位置
• 常に表示される新規追加行のフォーム、複数行の削除、シングルクリックでの編集
• 特定のインデックスに新しい行を保存する、インラインテンプレート編集

📄 参照： references/editing-validation.md

• 列ごとの ValidationRules、データ注釈属性（[Required]、[Range] など）
• カスタム検証属性、複合型の検証、カスタムバリデーターコンポーネント

選択

📄 参照： references/selection.md

• AllowSelection、SelectionMode、SelectionType、チェックボックスによる選択、プログラムによる選択

📄 参照： references/clipboard.md

• クリップボードへのコピー（Ctrl+C／Ctrl+Shift+H）、CopyAsync、オートフィルのドラッグハンドル、貼り付け（Ctrl+V）、バッチ編集の要件

集計

📄 参照： references/aggregates.md

• GridAggregates、AggregateType、FooterTemplate、GroupFooterTemplate、GroupCaptionTemplate、リアクティブな集計

行の機能とテンプレート

📄 参照： references/row-features.md

• RowDataBound、行のドラッグ＆ドロップ、行の高さ、行の結合、RowTemplate

📄参照： references/templates-structural.md

• ColumnTemplate（画像、ハイパーリンク、チェックボックス、SfChip）、HeaderTemplate、RowTemplate、RowTemplate の書式設定、DetailTemplate、展開／折りたたみ API、読み込み時に展開する、展開アイコンを非表示にする、カスタム CSS アイコン、階層型の入れ子 Grid

📄 参照： references/templates-interactive.md

• ToolbarTemplate、列の EditTemplate、GridEditSettings の Template、追加時と編集時で入力を無効にする、三連アンダースコアによる入れ子のバインド、ダイアログを開いたときにエディターにフォーカスする、RowUpdating による変換、FooterTemplate、CaptionTemplate、キャプション内のカスタム Blazor コンポーネント、ロケールのカスタマイズ、PagerTemplate

ツールバー、コンテキストメニュー

📄 参照： references/toolbar.md

• 組み込み／カスタムのツールバー項目、OnToolbarClick、ToolbarTemplate

📄 参照： references/context-menu.md

• ContextMenuItems、カスタム項目、ContextMenuItemClicked

エクスポートと印刷

📄 参照： references/excel-export.md

• AllowExcelExport、ExportToExcelAsync、ExcelExportProperties、テーマ／テンプレートのエクスポート

📄 参照： references/pdf-export.md

• AllowPdfExport、ExportToPdfAsync、PdfExportProperties、テンプレートの PDF エクスポート

📄 参照： references/print.md

• PrintAsync、PrintMode

パフォーマンス、イベント、状態

📄 参照： references/performance.md

• SetRowDataAsync、PreventRender、WebAssembly の最適化、列の仮想化に関するヒント

📄 参照： references/events.md

• GridEvents の完全なリファレンス：編集、選択、フィルター、並べ替え、グループ化、ページ、ツールバー、エクスポートに関するすべてのイベント

📄 参照： references/state-management.md

• EnablePersistence、GetPersistDataAsync、SetPersistDataAsync、ResetPersistDataAsync

スタイル設定とアダプティブ UI

📄 参照： references/style-and-appearance.md

• Grid、ヘッダー、行、フィルタリング、編集、グループ化、集計の CSS クラス

📄 参照： references/adaptive-layout.md

• EnableAdaptiveUI、RowRenderingMode、AdaptiveUIMode、モバイル対応パターン

クイックスタート

@page "/datagrid-demo"
@using Syncfusion.Blazor.Grids

<SfGrid DataSource="@Orders" AllowPaging="true" AllowSorting="true" AllowFiltering="true">
    <GridPageSettings PageSize="10"></GridPageSettings>
    <GridColumns>
        <GridColumn Field="OrderID"    HeaderText="Order ID"   IsPrimaryKey="true" Width="120" TextAlign="TextAlign.Right"></GridColumn>
        <GridColumn Field="CustomerID" HeaderText="Customer"   Width="150"></GridColumn>
        <GridColumn Field="Freight"    HeaderText="Freight"    Format="C2" Width="120" TextAlign="TextAlign.Right"></GridColumn>
        <GridColumn Field="OrderDate"  HeaderText="Order Date" Format="d"  Width="150" Type="ColumnType.Date"></GridColumn>
        <GridColumn Field="ShipCountry" HeaderText="Ship Country" Width="150"></GridColumn>
    </GridColumns>
</SfGrid>

@code {
    public List<Order> Orders = new List<Order>
    {
        new Order { OrderID = 10248, CustomerID = "VINET", Freight = 32.38, OrderDate = new DateTime(1996,7,4), ShipCountry = "France" },
        new Order { OrderID = 10249, CustomerID = "TOMSP", Freight = 11.61, OrderDate = new DateTime(1996,7,5), ShipCountry = "Germany" },
    };
    public class Order
    {
        public int OrderID { get; set; }
        public string CustomerID { get; set; }
        public double Freight { get; set; }
        public DateTime OrderDate { get; set; }
        public string ShipCountry { get; set; }
    }
}

よく使うパターン

編集＋ツールバーを備えた Grid

<SfGrid DataSource="@Orders" Toolbar="@(new List<string>() { "Add","Edit","Delete","Update","Cancel" })">
    <GridEditSettings AllowAdding="true" AllowEditing="true" AllowDeleting="true" Mode="EditMode.Normal"></GridEditSettings>
    <GridColumns>
        <GridColumn Field="OrderID" IsPrimaryKey="true" ValidationRules="@(new ValidationRules{Required=true})"></GridColumn>
        <GridColumn Field="CustomerID" ValidationRules="@(new ValidationRules{Required=true})"></GridColumn>
        <GridColumn Field="Freight" EditType="EditType.NumericEdit"></GridColumn>
    </GridColumns>
</SfGrid>

グループ化＋ページングを備えた Grid

<SfGrid DataSource="@Orders" AllowGrouping="true" AllowPaging="true">
    <GridGroupSettings Columns="@(new string[]{"ShipCountry"})"></GridGroupSettings>
    <GridPageSettings PageSize="10"></GridPageSettings>
    <GridColumns>
        <GridColumn Field="OrderID" Width="120"></GridColumn>
        <GridColumn Field="CustomerID" Width="150"></GridColumn>
        <GridColumn Field="ShipCountry" Width="150"></GridColumn>
    </GridColumns>
</SfGrid>

プログラム制御用 Grid リファレンス

<SfGrid @ref="Grid" DataSource="@Orders">...</SfGrid>
@code {
    SfGrid<Order> Grid;
    // Programmatic operations:
    // await Grid.SortColumnAsync("OrderID", SortDirection.Ascending, false);
    // await Grid.FilterByColumnAsync("ShipCountry", "equal", "France");
    // await Grid.GoToPageAsync(2);
    // await Grid.StartEditAsync();
    // await Grid.SelectRowAsync(0);
}

主なプロパティ一覧

プロパティ	説明
DataSource	IEnumerable<T> または DataManagerRequest をバインドします
AllowPaging	ページングを有効にします
AllowSorting	並べ替えを有効にします
AllowFiltering	列のフィルタリングを有効にします
AllowGrouping	行のグループ化を有効にします
AllowSelection	行／セルの選択を有効にします
Height / Width	スクロール用の固定サイズを指定します
Toolbar	組み込みまたはカスタムのツールバー項目です
EnableVirtualization	大量データ向けの行の仮想化
EnableInfiniteScrolling	無限スクロールでの読み込み
EnablePersistence	状態を localStorage に保存します
EnableAdaptiveUI	モバイル対応のレンダリング