syncfusion-react-form-builder

Syncfusion React Form Builder

Syncfusion Form Builder を使用して、編集可能な React フォームを作成、トラブルシューティング、または拡張する必要がある場合に、このスキルを使用してください。Form Builder は、スキーマ駆動のフォーム定義を生成するビジュアルデザイナーです。ユーザーはフィールドをキャンバスにドラッグし、プロパティパネルで設定し、結果をプレビューして、Form Renderer で使用するスキーマをエクスポートできます。

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

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

• Vite の React アプリを作成し、Syncfusion Form Builder パッケージをインストールする
• ツールボックス、キャンバス、プロパティパネル、コードビュー、プレビューを備えたビジュアルフォームデザイナーを表示する
• schema プロパティを通じて初期フォームを読み込む
• properties でフィールドを定義し、layout で配置し、フォーム全体の settings を設定する
• エクスポート、プレビュー、永続化、RTL、モード、テンプレート、ツールボックス項目などの Form Builder プロパティを設定する
• Basic、Advanced、Layout のツールボックスカテゴリからフィールドを選択する
• フィールドのプロパティをカスタマイズし、プロパティパネルの項目を追加または非表示にして、デザイナーを更新する
• カスタムツールボックステンプレートを定義し、setFieldValue でテンプレートの値を同期する
• フィールドのドラッグ開始、ドラッグオーバー、ドロップ、プロパティ変更イベントを処理する
• 生成された JSON スキーマを確認、コピー、インポート、またはエクスポートする
• 検証、条件、式、依存ドロップダウン、動的範囲、リモートデータ、または Data Grid フィールドを含むスキーマを準備する

このスキルはフォームの設計と編集を対象としています。完成したスキーマをエンドユーザー向けにレンダリングすること、送信された値を処理すること、またはレンダラーのフォームアクションを設定することが主な目的の場合は、React Form Renderer スキルを使用してください。

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

コンポーネント API とイベント

📄 参照: references/getting-started.md

• Form Builder のすべてのプロパティ、型、デフォルト値
• Simple モードと Developer モード
• schema、エクスポート、プレビュー、永続化、RTL、テンプレート、ツールボックスの設定

はじめに

📄 参照: references/getting-started.md

• CSS テーマのインポートを含む Vite と React のセットアップ
• Form Builder の基本的な使い方
• フォームスキーマをコンポーネントにバインドする方法
• フォームを作成するための最小構成の実用例

スキーマと初期フォームのセットアップ

📄 最初に参照: references/form-schema.md

• schema プロパティとルートスキーマの構造
• properties でのフィールド定義と、layout でのレンダリング順序
• フォーム設定、サポートされるウィジェット、レイアウトコンテナー
• 要求された各フィールドを、ドキュメントに記載された widget と type に対応付ける方法

利用者が初期フォームを備えた React Form Builder を求めている場合は、references/getting-started.md に従って Vite と React のコンポーネントをセットアップし、references/form-schema.md を使用して初期 schema を定義してください。要求されたスキーマに次の動作が必要な場合は、該当するリファレンスを参照してください。

• 検証ルール: references/validations.md
• 条件付き動作: references/conditions.md
• 計算値: references/expressions.md
• 依存ドロップダウン: references/dependent-dropdown.md
• 動的な数値／日付／時刻の範囲: references/min-max-range.md
• リモートのドロップダウン、複数選択、またはチェックボックスグループのデータ: references/remote-data-binding-in-components.md
• Data Grid フィールドとデータソース: references/data-grid-features.md

フィールドコンポーネントパネル

📄 参照: references/field-components-panel.md

• Fields タブと Templates タブ
• Basic、Advanced、Layout カテゴリ
• 検索／フィルターの動作とツールボックスのカスタマイズ
• カスタムテンプレートライブラリと formTemplates

プロパティパネル

📄 読む： references/property-panel.md

• 選択したフィールドにパネルが表示されるタイミング
• Display、Validation、Conditions、Layout、Data の各タブ
• setProperty と getProperty のパターン
• 自動保存とプロパティ更新の動作

プレビューと JSON

📄 読む： references/preview-tab.md

• プレビュータブのワークフロー
• enablePreview によるプレビューの無効化
• JSON スキーマの確認とコピー操作

テンプレート

📄 読む： references/templates.md

• toolboxItems を使用したカスタムツールボックステンプレートの定義
• エクスポート時の templateId の使用
• サードパーティコンポーネントとスキーマのマッピング

フォーム設定

📄 読む： references/form-settings.md

• フォーム全体のタイトルと幅
• Hide Label、Size、Float Label Type などのレイアウトレベルの設定
• 個々のフィールドに影響を与えずにフォーム全体の設定を適用

エクスポートとインポート

📄 読む： references/export-import.md

• Form Renderer で再利用するためのスキーマのエクスポート
• 既存のスキーマを Form Builder にインポート
• allowExport によるエクスポートの無効化

クイックスタート

1. パッケージをインストールします。

npm install @syncfusion/ej2-react-form-builder @syncfusion/ej2-material3-theme

2. コンポーネントをインポートし、初期スキーマをバインドします。

import { FormBuilderComponent } from '@syncfusion/ej2-react-form-builder';
import '@syncfusion/ej2-material3-theme/styles/material3.css';

const formSchema = {
  version: '0.1.0',
  properties: {
    emailAddress: {
      id: 'textbox_1785491685456_167',
      name: 'emailAddress',
      type: 'string',
      label: 'Email Address',
      textboxType: 'email',
      required: true,
      placeholder: 'Enter your email',
      widget: 'textbox'
    }
  },
  layout: [{ type: 'field', propertyId: 'emailAddress' }],
  settings: { name: 'Untitled Form' }
};

export default function App() {
  return <FormBuilderComponent schema={formSchema} />;
}

3. npm run dev で Vite アプリケーションを起動し、ツールボックスとプロパティパネルを使ってフォームを編集します。プロジェクトの作成、テーマの設定、初期設定の全手順については、references/getting-started.md をお読みください。

よくあるパターン

ツールボックスのカスタマイズ

toolboxCategories を使用して、ツールボックスに表示するフィールドタイプと、それらを分類するカテゴリを指定します。

import { FormBuilderComponent } from '@syncfusion/ej2-react-form-builder';
import { ComponentCategory, FormWidgetType } from '@syncfusion/ej2-form-builder';

const toolboxCategories = [
  {
    category: ComponentCategory.Basic,
    items: [FormWidgetType.Textbox, FormWidgetType.Textarea]
  },
  {
    category: ComponentCategory.Advanced,
    items: [FormWidgetType.Date, FormWidgetType.DateRange]
  }
];

プロパティの動的な追加

setProperty を使用してウィジェットにカスタムプロパティを追加し、refresh() でパネルを更新します。

formBuilderRef.current?.setProperty(FormWidgetType.Textarea, {
  key: 'enableRtl',
  label: 'Enable RTL',
  type: 'boolean',
  default: false
});

カスタムテンプレートの登録

toolboxItems でサードパーティのカスタムコントロールを定義し、値が変更されたときに setFieldValue を呼び出します。

<FormBuilderComponent
  toolboxItems={[{ type: FormWidgetType.Textbox, template: inputTemplate }]}
/>;

プレビューと JSON 出力の使用

プレビュータブに切り替えてレイアウトと操作を検証し、JSON タブを開いてエクスポートされたスキーマを確認し、Form Renderer で使うためにコピーします。

よくあるパターン

• すべてのフィールドを properties に保持し、propertyId を使って layout から参照します。
• 各フィールドには、安定した一意の name と id を設定します。条件、式、依存データでは、ドキュメントに記載されている id と name の参照を使用します。
• 各フィールドの widget と type を、references/form-schema.md に記載されているサポート対象スキーマ一覧に合わせます。
• toolboxCategories または toolboxItems を使用して、ビジュアルツールボックスで利用できるフィールドを指定します。
• 再利用可能な完全なスキーマには formTemplates を、サードパーティコントロールにはカスタムツールボックステンプレートを使用します。
• プレビューでフォームを検証し、JSON タブを確認して、スキーマとレイアウトが正しいことを確かめてからエクスポートします。
• デザイナーの操作状態には API イベントのペイロードを使用し、実行時の値や送信時の動作には Form Renderer のイベントを使用します。

実装チェックリスト

Form Builder フォームを作成または修正する際は、次の点を確認してください。

• React パッケージとテーマがインストールされ、FormBuilderComponent がインポートされている
• schema の値がオブジェクト、JSON 文字列、またはサポート対象のスキーマインスタンスである
• すべてのフィールドに一意の name、安定した id、サポート対象の widget、対応する type が設定されている
• すべての layout フィールドノードが有効な propertyId を参照している
• レイアウトコンテナーは layout に、子フィールドは properties に保持されている
• バリデーション、条件、式、範囲、データソースが、ドキュメントに記載されている参照形式を使用している
• カスタムテンプレートが setFieldValue で Form Builder の状態を更新している
• 要求されるワークフローに応じて、プレビューとエクスポートが有効または無効になっている
• カスタムコンポーネントの ref が、ドキュメントに記載されている React の useRef パターンを使用している

一般的なワークフロー

• まず基本スキーマを作成し、ビルダーに読み込みます。
• ツールボックスのカテゴリと定義済みテンプレートを使って、フォームのデザインを構成します。
• 右側のペインでフィールドのプロパティを編集し、検証、レイアウト、表示動作を設定します。
• スキーマをエクスポートする前に、プレビューで最終的なフォームを検証します。
• 後からスキーマを再インポートして、編集を続けたり、生成済みのフォームを調整したりできます。