syncfusion-blazor-dataform

Syncfusion Blazor DataForm コンポーネントの実装

Syncfusion Blazor DataForm コンポーネントを実装するための包括的なスキルです。Blazor アプリケーションにおけるフォームのインストール、構成、データバインディング、検証、イベント処理、テンプレート化、カスタマイズについて説明します。

コンポーネントの概要

Syncfusion Blazor DataForm（SfDataForm）は、動的でデータ駆動型のフォームを効率よく作成できる強力なフォームコンポーネントです。検証、フィールドのバインディング、イベント処理を自動化できます。次の機能をサポートしています。

• モデルのプロパティからのフィールドの自動生成
• データアノテーションとカスタムルールによる組み込みの検証
• 複数のバインディング方法（Model、EditContext）
• 列、グループ化、セクションを使ったカスタマイズ可能なレイアウト
• カスタムフィールドデザイン向けのテンプレートベースのレンダリング
• フォームやフィールド単位の反応を処理するイベント駆動型アーキテクチャ
• 検証メッセージと UI テキストのローカライズ対応
• 適切なラベルと ARIA 属性を備えたアクセシブルなフォーム表示

ドキュメントとナビゲーションガイド

はじめに

📄 参照先: references/getting-started.md

まずはこちらをご覧ください。インストール、NuGet パッケージの設定、名前空間のインポート、サービスの登録、テーマの構成、基本的な DataForm の例について説明しています。

• インストールと NuGet パッケージ
• Blazor プロジェクトのセットアップ（Server/WebAssembly/Web App）
• 名前空間のインポートとサービスの登録
• テーマのセットアップと構成
• 基本的な DataForm の作成
• 最初のフォームの実行

フォーム項目とフィールドの構成

📄 参照先: references/form-items.md

フォーム項目の定義、ラベル、プレースホルダー、ヒント、エディターの種類の構成、個々のフィールド動作のカスタマイズ方法について説明します。

• FormItem 要素の構成
• ラベルとプレースホルダーの構成
• エディターの種類の選択
• フィールドの無効化と非表示
• カスタム属性（必須、パターン、データアノテーション）
• フォームのグループ化と列の配置

フォームフィールドの自動生成

📄 参照先: references/autogeneration.md

FormAutoGenerateItems を使ってモデルのプロパティからフォームフィールドを自動生成する方法を説明します。型のマッピングや、自動生成フィールドとカスタムフィールドの組み合わせについても取り上げます。

• FormAutoGenerateItems の概要
• 型とコンポーネントのマッピング（int、string、DateTime、bool、enum など）
• プリミティブ型のフィールドの自動生成
• 自動生成フィールドとカスタムフィールドの組み合わせ
• 特定のフィールドの自動生成のキャンセル
• 構成オプション

データバインディング

📄 参照先: references/data-binding.md

モデルバインディング、EditContext バインディング、双方向データバインディング、複雑なデータ構造へのバインディングについて説明します。

• モデルバインディングの基本
• EditContext バインディングの方法
• フォーム単位およびフィールド単位のバインディング
• ネストされたオブジェクトとの双方向バインディング
• 複雑なモデルへのバインディング
• データの初期化と既定値
• フォーム名と ID の構成

フォームの検証

📄 参照先: references/validation.md

データアノテーション、カスタム検証ルール、Fluent Validation との統合、エラーメッセージの表示を使ったフォーム検証について説明します。

• データアノテーションによる検証（Required、Range、EmailAddress など）
• DataAnnotationsValidator のセットアップ
• カスタム検証属性とルール
• Fluent Validation フレームワークとの統合
• 複雑なモデルの検証シナリオ
• 検証メッセージの表示
• IsValid() メソッドと検証状態
• 条件付き検証

フォームとフィールドのイベント

📄 参照先: references/events.md

ユーザー操作やフォーム状態の変化を処理するための、フォーム送信イベントとフィールド単位のイベントについて説明します。

• OnSubmit イベント（送信を試みるたびに発生）
• OnValidSubmit イベント（有効な送信の場合にのみ発生）
• OnInvalidSubmit イベント（検証に失敗した場合にのみ発生）
• OnUpdate イベント（フィールド値の変更時に発生）
• イベント引数と EditContext へのアクセス
• 非同期イベントハンドラー
• 一般的なイベントパターン

レイアウトのカスタマイズ

📄 参照： references/layout-customization.md

列、列の幅、ラベルの配置、フローティングラベル、カスタムボタンの配置を使用して、フォームのレイアウトをカスタマイズします。

• 列レイアウトの設定
• 列幅と行幅
• 列数とレスポンシブ対応
• ラベルの配置（上、左、フローティング）
• フローティングラベルのスタイル設定
• ボタンの整列と配置
• カスタム送信／リセットボタン
• FormGroup によるフォームのグループ化

テンプレートとカスタムレンダリング

📄 参照： references/templates.md

render fragment を使用する FormTemplate と FormItemTemplate によって、カスタムのフォームレイアウトとフィールドのレンダリングを作成します。

• フォーム全体のレイアウトをカスタマイズする FormTemplate
• 個々のフィールドをレンダリングする FormItemTemplate
• テンプレートのコンテキストと変数
• カスタムエディターのレンダリング
• render fragment と構成
• 高度なテンプレートパターン
• テンプレートの再利用性

ローカライズ

📄 参照： references/localization.md

複数の言語で検証メッセージ、フォームラベル、エラーメッセージを表示できるようにローカライズを設定します。

• 組み込みのローカライズリソース
• エラーメッセージのローカライズ
• カスタムローカライズの設定
• カルチャと言語の設定
• RTL（右から左）への対応

クイックスタートの例

開始するための、最小限の動作例を紹介します。

@page "/dataform-example"
@using System.ComponentModel.DataAnnotations
@using Syncfusion.Blazor.DataForm

<SfDataForm ID="MyDataForm"
            Model="@employeeModel">
    <FormValidator>
        <DataAnnotationsValidator></DataAnnotationsValidator>
    </FormValidator>
    <FormItems>
        <FormAutoGenerateItems></FormAutoGenerateItems>
    </FormItems>
</SfDataForm>

@code {
    public class EmployeeModel
    {
        [Required(ErrorMessage = "First Name is required")]
        [Display(Name = "First Name")]
        public string FirstName { get; set; }

        [Required(ErrorMessage = "Email is required")]
        [EmailAddress(ErrorMessage = "Invalid email address")]
        [Display(Name = "Email")]
        public string Email { get; set; }

        [Range(18, 65, ErrorMessage = "Age must be between 18 and 65")]
        [Display(Name = "Age")]
        public int Age { get; set; }

        [Display(Name = "Date of Birth")]
        public DateTime? DateOfBirth { get; set; }
    }

    private EmployeeModel employeeModel = new EmployeeModel();
}

よくあるパターン

パターン 1：検証と送信を行うフォーム

<SfDataForm ID="ContactForm" Model="@contact" OnValidSubmit="HandleValidSubmit">
    <FormValidator>
        <DataAnnotationsValidator></DataAnnotationsValidator>
    </FormValidator>
    <FormItems>
        <FormItem Field="@nameof(contact.Name)" LabelText="Full Name"></FormItem>
        <FormItem Field="@nameof(contact.Email)" LabelText="Email Address"></FormItem>
        <FormItem Field="@nameof(contact.Message)" EditorType="FormEditorType.TextArea"></FormItem>
    </FormItems>
</SfDataForm>

@code {
    private Contact contact = new();

    private async Task HandleValidSubmit(EditContext context)
    {
        // Save contact to database
        await SaveContactAsync(contact);
    }
}

パターン 2：カスタムフィールドを使用した自動生成フォーム

<SfDataForm Model="@product">
    <FormItems>
        <FormItem Field="@nameof(product.Name)" LabelText="Product Name"></FormItem>
        <FormAutoGenerateItems></FormAutoGenerateItems>
        <FormItem Field="@nameof(product.Category)" EditorType="FormEditorType.DropDownList"></FormItem>
    </FormItems>
</SfDataForm>

@code {
    private Product product = new();
}

パターン 3：連動するフィールドを持つフォーム

<SfDataForm Model="@order" OnUpdate="HandleFieldUpdate">
    <FormItems>
        <FormItem Field="@nameof(order.Country)" LabelText="Country"></FormItem>
        <FormItem Field="@nameof(order.City)" LabelText="City"></FormItem>
        <FormAutoGenerateItems></FormAutoGenerateItems>
    </FormItems>
</SfDataForm>

@code {
    private Order order = new();

    private async Task HandleFieldUpdate(FormUpdateEventArgs args)
    {
        if (args.FieldName == nameof(Order.Country))
        {
            // Update cities based on selected country
            order.City = await GetCitiesForCountryAsync(order.Country);
        }
    }
}

パターン 4：列を使用したカスタムレイアウト

<SfDataForm Model="@employee" ColumnCount="2">
    <FormItems>
        <FormItem Field="@nameof(employee.FirstName)" LabelText="First Name" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.LastName)" LabelText="Last Name" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.Email)" LabelText="Email" ColumnSpan="2"></FormItem>
        <FormItem Field="@nameof(employee.Department)" LabelText="Department" ColumnSpan="1"></FormItem>
        <FormItem Field="@nameof(employee.Salary)" LabelText="Salary" ColumnSpan="1"></FormItem>
    </FormItems>
</SfDataForm>

@code {
    private Employee employee = new();
}

主なプロパティとメソッド

共通プロパティ

プロパティ	型	目的
Model	object	フォームにバインドされたデータモデル
EditContext	EditContext	高度なバインディングシナリオ向けの Blazor EditContext
ColumnCount	int	フォームレイアウトの列数
OnValidSubmit	EventCallback	有効なデータでフォームが送信されたときに呼び出されます
OnInvalidSubmit	EventCallback	無効なデータでフォームが送信されたときに呼び出されます
OnSubmit	EventCallback	送信が試行されるたびに呼び出されます
OnUpdate	EventCallback	フィールドの値が変更されたときに呼び出されます

使用可能な FormEditorType の値

重要：ほとんどの場合、DataForm がモデルのプロパティ型に基づいて適切なエディターを自動選択するため、EditorType を指定する必要はありません。これらの値は、デフォルトの動作を上書きする必要がある場合にのみ使用してください。

FormEditorType	用途	使用するタイミング
TextBox	1 行のテキスト入力	文字列フィールドのデフォルト動作を上書きする場合（デフォルトでは不要）。数値型では不要です
TextArea	複数行のテキスト入力	文字列プロパティで複数行のテキスト入力が必要な場合
DatePicker	日付のみの選択	DateTime のデフォルト動作を上書きする場合（DateTime のデフォルト）
DateTimePicker	日付と時刻の選択	DateTime プロパティで日付と時刻の両方が必要な場合
TimePicker	時刻のみの選択	TimeSpan または DateTime で時刻のみの選択が必要な場合
DropDownList	リストからのドロップダウン選択	enum またはカスタムリストから選択する場合
ComboBox	フィルター機能付きの編集可能なドロップダウン	検索可能なドロップダウンが必要な場合
AutoComplete	候補を使ったオートコンプリート	入力候補機能が必要な場合
Checkbox	ブール値の切り替え（小文字の「b」に注意）	bool のデフォルト動作を上書きする場合。CheckBox ではありません
Switch	ブール値用のトグルスイッチ	bool プロパティでチェックボックスの代わりに使用する場合
Password	マスキング付きのパスワード入力	パスワード文字列フィールド用

重要な注意事項：

• ⚠️ 型の自動マッピング：DataForm は C# の型を適切なエディターに自動的にマッピングします：
  • int、long、decimal、double、float → 数値テキストボックス（EditorType は不要）
  • string → テキストボックス（EditorType は不要）
  • bool → チェックボックス（EditorType は不要）
  • DateTime → DatePicker（EditorType は不要）
  • enum → DropDownList（EditorType は不要）
• ⚠️ CheckBox（大文字の「B」）ではなく、Checkbox（小文字の「b」）を使用してください
• ⚠️ NumericTextBox というエディター型はありません。数値型のプロパティに基づいて、数値入力の動作が自動的に適用されます
• ⚠️ デフォルトの動作を上書きする場合にのみ EditorType を指定してください

一般的なメソッド

メソッド	目的
Refresh()	フォームを更新し、フィールドを再描画します
Submit()	フォームをプログラムから送信します
Reset()	フォームをクリアし、初期値に戻します
IsValid()	フォームが有効かどうかを確認します
Validate()	送信せずに検証を実行します

EditorType に関する重要なガイドライン

EditorType を使って FormItem 要素を設定する際は、次の重要な点に注意してください。

1. エディターの自動選択：DataForm はモデルのプロパティ型に基づいて適切なエディターを自動選択します。デフォルトの動作を上書きする場合を除き、通常は EditorType を指定する必要はありません。

   • 数値プロパティ（int、long、float、decimal、double）→ 数値テキストボックスとして自動的に表示されます
   • 文字列プロパティ → テキストボックスとして自動的に表示されます
   • ブール値プロパティ → チェックボックスとして自動的に表示されます
   • DateTime プロパティ → 日付選択として自動的に表示されます
   • Enum プロパティ → ドロップダウンとして自動的に表示されます

2. EditorType を指定する場合：デフォルトの動作を上書きする場合にのみ EditorType を指定してください。

   • 文字列の複数行入力には FormEditorType.TextArea を使用します
   • ブール値でチェックボックスの代わりに FormEditorType.Switch を使用します
   • 時刻も含む DateTime には、DatePicker の代わりに FormEditorType.DateTimePicker を使用します
   • パスワード文字列には FormEditorType.Password を使用します
   • カスタムリストには FormEditorType.DropDownList または ComboBox を使用します

3. Checkbox の大文字・小文字：チェックボックスを明示的に指定する場合は、FormEditorType.CheckBox ではなく、小文字の「b」を使った FormEditorType.Checkbox を使用してください。

4. NumericTextBox 型はありません：FormEditorType.NumericTextBox はありません。数値型のプロパティに基づいて、数値入力の動作が自動的に適用されます。

例：

<FormItem Field="@nameof(model.Quantity)" 
          LabelText="Quantity">
</FormItem>


<FormItem Field="@nameof(model.IsActive)" 
          LabelText="Is Active">
</FormItem>


<FormItem Field="@nameof(model.Description)" 
          LabelText="Description"
          EditorType="FormEditorType.TextArea">
</FormItem>


<FormItem Field="@nameof(model.IsEnabled)" 
          LabelText="Enabled"
          EditorType="FormEditorType.Switch">
</FormItem>

関連スキル

• Syncfusion Blazor Components - すべての Blazor コンポーネント向けのメインライブラリスキル
• AutoComplete - ドロップダウンフィールドエディター向け
• File Upload - ファイル入力フィールド向け