Form

Form は、関連するフィールドをまとめて入力、検証、送信するためのコンポーネントです。申請、登録、設定、レコード編集、ワークフローの各ステップに適しています。Form はフィールドのセクション、レイアウト、検証状態、送信範囲を一元管理します。

1. Form の機能と設定項目

Form の設定は 4 つのレベルに分かれます。

Form：レイアウト、モード、データ読み込み、送信、下書き、公開状態を管理します。
Form Section：業務上のテーマごとにフィールドを整理し、繰り返しコレクションとしても設定できます。
Field：ラベル、Field Key、初期値、行の占有方法、条件、検証ルールを設定します。
Button Set / Interaction：Reset、Validate、Submit、コンポーネント関数を組み合わせます。

1.1 プロパティと機能の一覧

設定領域	主なプロパティまたは機能	用途
構造	ID / Name、Form Sections、Fields、Button Set	Form の境界、業務グループ、送信範囲を定義
レイアウト	Controls Per Row、Form column split、Layout、Label Alignment、Full row	フィールド数、ラベル幅、配置、全幅フィールドを調整
モード	Create、Edit、View、Warn about unsaved changes	新規作成、編集、読み取り専用、未保存警告を管理
データアダプター	Load / Create / Update URL、Response Data Path、Record ID、Revision	レコードを読み込み、楽観ロック付き API に接続
送信	Full values、Changed values only、Custom URL	全値または変更された値だけを送信
検証	Required、Length、Pattern、Number、Custom Validator、Remote validation	ローカル、リモート、サーバーのフィールドエラーを表示
条件	Visible / Disabled / Required When、Dependencies、Clear When Hidden	他のフィールド、Page Context、現在のモードに応じて動作
繰り返しグループ	Collection Key、Minimum / Maximum Items、Add / Delete	連絡先や明細などのオブジェクト配列を編集
下書き	Browser / Remote storage、Draft Key、Autosave Delay、revision	未完了の入力を保存、復元、破棄
操作と状態	reset、validate、submit、saveDraft、restoreDraft、discardDraft、`forms.*`	操作を構成し valid、dirty、submitting などを参照
フィールド生成	Business Object、JSON Schema、OpenAPI	既存モデルから編集可能なフィールド構造を生成

1.2 構造と送信範囲

Form は状態と送信範囲の境界です。1 ページに複数の Form を置いても、それぞれは自身の Sections、Fields、Button Set だけを管理します。

Form Section は業務上のグループを表し、単なる余白ではありません。
Field Key は Form 状態と送信 JSON の安定した名前で、バックエンド DTO と合わせます。
Button Set は操作を配置し、実際に Reset、Validate、Submit のどれを実行するかは Interaction で設定します。
Submit Form は対象 Form に登録されたフィールドだけを収集し、別の Form、Page Context、Tree Current Record は自動では含めません。

検索 Form と編集 Form を同じページに置く場合は別々の ID を付け、各操作から対象を明示してください。

1.3 レイアウトとレスポンシブ動作

Controls Per Row は 1 行の最大フィールド数と各フィールドのグリッド幅を決めます。Form column split はその領域を Label と Content に分割し、2 項目/行では合計 12、1 項目/行では合計 24 になります。

Layout は Horizontal、Vertical、Inline を選択できます。Label Alignment は Horizontal のラベル文字だけに作用します。Full row / Start on new row は長いフィールドを 1 行にしつつ、ラベルを通常フィールドと揃えます。狭い画面では読書順に積み重なるため、モバイル専用 Form は不要です。

1.4 モード、データ読み込み、送信

モード	動作	一般的なエンドポイント
Create	初期値から新規レコードを作成	Create URL、通常 POST
Edit	レコードを読み込んで変更を送信	Load URL + Update URL、通常 PUT / PATCH
View	同じラベル/値レイアウトを読み取り専用で表示	Load URL、編集操作なし

Data adapter は Response Data Path からレコードを取得し、Record ID Field と Revision Field で識別子と楽観ロックを保持します。読み込み後の値が Reset と Changed values only の基準です。単純な送信には Custom URL、読み込み、競合検出、下書き復元まで必要な場合は完全な Data adapter を使用します。

1.5 検証、フィールドエラー、条件

Required、Length、Pattern、Number、Custom Validator は即時のローカル検証です。Remote validation はメール、ユーザー名、業務コードなどをバックエンドで確認し、トリガーと Debounce を設定できます。送信時にバックエンドが fieldErrors を返すと、Form は Field Key ごとにメッセージを表示します。

Visible When、Disabled When、Required When は state.*、context.*、record.*、form.* を参照します。Dependencies は再計算する Field Key を宣言し、Clear When Hidden は非表示になった古い値を削除します。画面上の非表示やクライアント検証は、サーバー側の権限や検証の代わりにはなりません。

1.6 繰り返しグループと下書き

繰り返し Form Section では、内部 Fields が 1 行のテンプレートになります。Collection Key は送信 JSON のオブジェクト配列で、Minimum / Maximum Items が行数を制限し、Runtime が Add / Delete を提供します。エラーパスには配列インデックスが残るため、対象行を特定できます。

下書きは正式な業務レコードではなく未送信の Form 状態です。Browser storage は単一端末の短期入力、Remote service は Load / Save URL、Draft Key、revision を使う重要または複数端末の入力に適しています。revision 競合を黙って上書きしてはいけません。

1.7 操作と公開状態

操作	動作
`reset`	読み込み済みの基準値または Create の初期値へ戻し、エラーを消去
`validate`	現在の Form を検証し、失敗時は後続操作を停止
`submit`	検証、payload 作成、送信、フィールドエラー処理を実行
`saveDraft` / `restoreDraft` / `discardDraft`	下書きを保存、復元、破棄

式は forms.<formId>.valid、dirty、submitting、submitError、lastSubmit、mode を参照できます。これらは読み取り専用です。Step では Submit Form が成功した後だけ nextStep を実行できます。

1.8 フィールド生成とバックエンド連携

Generate fields は Business Object、JSON Schema、OpenAPI Schema から Sections と Fields を作成します。生成後も通常のページメタデータとして編集できるため、ラベル、機密フィールド、選択肢、権限、レイアウト、API を確認してください。

データ読み込み、リモート検証、下書き、送信には X-Spark-Page-Environment と X-Spark-Page-Render-Mode が自動で付与されます。DESIGN_PREVIEW では安定したテストデータ、RUNTIME では実際の Use Case を返せますが、認証、テナント分離、権限は別途必須です。

1.9 設定の選び方

目的	推奨する開始設定	参照する節
基本的な新規作成	Create + Sections + ローカル検証 + Custom URL	2～8
既存レコードの編集	Edit + Load / Update URL + Record ID / Revision	9、10、14
読み取り専用	View + Load URL	10
動的フィールド	Conditions + Dependencies	11、12
連絡先や明細	Repeatable Group	13
長時間入力	Draft + 未保存警告	15
モデルから生成	Generate fields	16

1.10 Form で利用できるフィールド

まずデータ形状からフィールドを選び、その後にレイアウト、検証、Interaction を設定します。現在のパレットでは以下の 22 種類を追加できます。旧 Select、MultiSelect、旧 MultiRowInput は既存ページ互換のためだけに非表示で保持され、新規ページの入口にはなりません。

分類	フィールド	適したデータ
基本入力	Input、Address、Text Area	1 行テキスト、住所、長文
選択とユーザー	Select、Radio Button、Checkbox、Switch、Cascade Select、Tree Select、Transfer、User Select、Department Select	列挙値、階層、集合、ユーザー ID、部門 ID
日付と数値	Date Picker、Time Picker、Calendar、Rate、Slider	日付、時刻、評価、数値、範囲
エディター	Rich Text、Code Editor、JSON Editor	書式付き本文、スクリプト、JSON
ファイルと構造化データ	Upload、Multi-Row Input	ファイルメタデータ、オブジェクト配列

各ページで利用場面、主なプロパティ、送信値、条件、Interaction を説明します。外観だけでなくバックエンドのデータ契約に合わせて選択してください。

2. サンプル：従業員オンボーディング申請

Spark Sample の Form ページには、2 つのセクション、2 列レイアウト、全幅の理由入力欄、Reset / Validate / Submit 操作があります。

Screen
└── Form: Employee Onboarding Form
    ├── Employee details
    │   ├── Full name / Work email / Department
    │   └── Employment type / Start date
    ├── Equipment and access
    │   ├── Laptop budget / Administrator access
    │   └── Request justification（全幅）
    └── Reset / Validate / Submit request

3. Form とセクションを追加する

Screen、Panel、Grid Column、Tab、Step、Content のいずれかに Form を追加します。
Form を選択し、Form Sections に 1 つ以上のセクションを追加します。
セクションの Fields に Field、Select、RadioBox、DatePicker、Switch、TextArea などを追加します。
Form の Button Set に操作ボタンを追加します。
Form と各フィールドに安定した ID / Name を設定し、保存後に設計画面と実行画面を確認します。

セクションは「基本情報」「権限」「添付」「確認」のような業務上の意味で分けます。余白だけを作るための空セクションは避けてください。

4. レイアウト

Controls Per Row は通常フィールドを 1 行に最大何個表示するかを決めます。PC の業務フォームは 2、長文や狭い領域は 1、短い検索条件だけなら 3 または 4 が目安です。狭い画面では読み順に 1 列へ積み重なります。

内部は 24 列グリッドですが、分割は各フィールド領域内で計算されます。2 項目/行の場合、1 項目は 12 列です。

Label 4 + Content 8 = 12

1 項目/行なら 6 + 18 など合計 24 にします。Form column split の目盛りをドラッグすると Label と Content が同時に変わります。

TextArea などに Start on new row / Full row を有効にすると、ラベルは現在の比率を維持して上の先頭ラベルと揃い、内容部分だけが残りの列をまたぎます。

Layout	用途
Horizontal	ラベルと入力を横並びにする標準的な業務フォーム
Vertical	ラベルを上に置く。狭い領域や長いラベル向け
Inline	フィールドとボタンを 1 行に並べる短い検索バー向け

5. サンプルのフィールド

フィールド	コンポーネント	主な設定
Full name	Field	Required、Length `2–60`
Work email	Field	Required、メール Pattern
Department	Select	4 つの固定選択肢
Employment type	RadioBox	3 つの選択肢
Start date	DatePicker	`YYYY-MM-DD`
Laptop budget	Number Field	`500–5000`、接尾辞 `USD`
Administrator access	Switch	Default Checked はオフ
Request justification	TextArea	全幅、高さ `4–8`、Length `20–500`

Name / Field Key が送信 JSON のプロパティ名になります。同じ Form 内の編集フィールドには一意のキーを使用してください。

6. 検証

Required は未入力、Length は文字数、Pattern はメールなどの形式、Number は数値範囲、Custom Validator は業務固有ルールに使います。エラー時は該当フィールドの近くにメッセージが表示され、送信は停止します。

画面側の検証は即時フィードバックのためです。ブラウザを経由しない要求もあるため、バックエンドにも同等の検証が必要です。

7. Reset、Validate、Submit

Reset ボタンの onClick に Call Component Function を追加します。

Component: employee_onboarding_form
Function: reset

Reset は初期値に戻し、検証メッセージを消します。Validate では Validate Form を追加し、同じ Form を指定します。

Submit の設定：

Form: employee_onboarding_form
Submission Mode: Custom URL
URL: /spark/api/sample/form/requests
Method: POST

Spark は対象 Form を検証し、その Form に登録されたフィールドだけを JSON として送信します。他の Form、Page Context、Tree の Current Record は混在しません。

8. Java バックエンドとページコンテキスト

@PostMapping
public ApiResult<FormRequestReceiptDTO> submit(
        @RequestBody FormRequestSubmission request,
        @RequestHeader(value = SparkPageRequestHeaders.ENVIRONMENT,
                required = false) String environment,
        @RequestHeader(value = SparkPageRequestHeaders.RENDER_MODE,
                required = false) String renderMode) {
    SparkPageRequestContext context =
            SparkPageRequestHeaders.resolve(environment, renderMode);
    return SparkApiResultHelper.success(
            Locale.JAPANESE,
            requestService.submit(request, context),
            "SPARK-SAMPLE-FORM-0001");
}

DESIGN_PREVIEW では保存しない安定したプレビュー受領結果を返し、RUNTIME では実際の UseCase を実行できます。Spark は X-Spark-Page-Environment と X-Spark-Page-Render-Mode を自動付与します。Interaction ごとに重複設定しないでください。詳細はページリクエストコンテキストを参照してください。

9. 高度なサンプル：従業員プロフィール編集

2 つ目のサンプルでは、レコード読み込み、メールのリモート検証、条件付き管理者アクセス理由、緊急連絡先の増減、下書き保存、変更項目だけの送信を扱います。

再現可能な定義は form-capabilities-page.json、バックエンドは FormCapabilityController と FormCapabilitySampleService にあります。

10. モードと公開状態

Form capabilities で Create / Edit / View を選択します。Edit は Load URL から読み込み Update URL へ保存し、View は同じレイアウトで読み取り専用表示します。未保存変更の警告も有効にできます。

forms.employee_profile_form.valid
forms.employee_profile_form.dirty
forms.employee_profile_form.submitting
forms.employee_profile_form.submitError
forms.employee_profile_form.lastSubmit
forms.employee_profile_form.mode

Form 内では form.dirty、form.submitting も使用できます。これらは読み取り専用です。

11. 条件付きフィールド

Visible When: state.adminAccess === true
Required When: state.adminAccess === true
Dependencies: adminAccess
Clear When Hidden: on

Visible / Disabled / Required は state.*、context.*、record.*、form.* の真偽式を使用します。Dependencies には依存する安定した Field Key をカンマ区切りで指定します。Clear When Hidden は非表示になった古い値を送信しないための設定です。

12. リモート検証とサーバーエラー

Work email の Validators に Remote validation を追加します。

Validation URL: /spark/api/sample/form/validate-email
Method: POST
Debounce: 400
Valid Response Path: data.valid
Message Response Path: data.message
Trigger: blur

新しい入力は前のリクエストをキャンセルし、古い応答は無視されます。保存時の業務検証は Field Key ごとのエラーを返します。

{
  "success": false,
  "fieldErrors": {
    "workEmail": ["このメールアドレスは使用済みです。"],
    "adminAccessReason": ["管理者アクセスが必要な理由を入力してください。"]
  }
}

Java では SparkFieldValidationException と Lattice Message を使用し、Web 境界で言語を解決します。

13. 繰り返しグループ

Form Section の Repeatable Group を有効にします。

Collection Key: emergencyContacts
Minimum Items: 1
Maximum Items: 3
Add Button Text: Add contact

Section 内のフィールドが 1 行のテンプレートになり、Runtime は Add/Delete と配列の検証パスを管理します。View では編集操作を表示しません。

14. データアダプターと変更セット

Load URL: /spark/api/sample/form/records/employee-1001
Create URL: /spark/api/sample/form/records
Update URL: /spark/api/sample/form/records/[[state.id]]
Response Data Path: data
Submission Payload: Changed values only
Record ID Field: id
Revision Field: revision

Edit は読み込み後に基準値を作り、recordId、revision、add/replace/remove の changes を送信します。Create は常に全値を送信します。古い revision の更新には HTTP 409 を返してください。

15. 下書き

個人の一時入力には Browser storage、端末をまたぐ重要な処理には Remote service を使用します。Draft Key、Autosave Delay、Load URL、Save URL を設定します。saveDraft、restoreDraft、discardDraft をボタンから呼び出せます。リモート下書きは保存後に新しい revision を返す必要があります。

16. モデルまたは Schema から生成

Form capabilities → Generate fields で Business Object、JSON Schema、OpenAPI を選び、Append または Replace を実行します。オブジェクト配列は Repeatable Group になります。生成物は通常の編集可能なページメタデータであり、Runtime がバックエンドの任意コンポーネント JSON やスクリプトを実行することはありません。

生成後にラベル、機密フィールド、選択肢、権限、URL、サーバー検証を確認してください。

17. トラブルシューティング

ラベルが揃わない： 2 項目/行なら 4 + 8 のように合計 12 にします。
条件付きフィールドが更新されない： Dependencies に制御元 Field Key を指定し、表示ラベルは使わないでください。
サーバーエラーが上部だけに出る： ルートの fieldErrors に正確な Field Key を返します。
下書き競合が続く： 保存後に返された新しい revision を次の保存で送信します。
設計プレビューで実データを作らない： DESIGN_PREVIEW ではプレビュー結果またはサンドボックスを使用します。

1. Form の機能と設定項目​

1.1 プロパティと機能の一覧​

1.2 構造と送信範囲​

1.3 レイアウトとレスポンシブ動作​

1.4 モード、データ読み込み、送信​

1.5 検証、フィールドエラー、条件​

1.6 繰り返しグループと下書き​

1.7 操作と公開状態​

1.8 フィールド生成とバックエンド連携​

1.9 設定の選び方​

1.10 Form で利用できるフィールド​

2. サンプル：従業員オンボーディング申請​

3. Form とセクションを追加する​

4. レイアウト​

5. サンプルのフィールド​

6. 検証​

7. Reset、Validate、Submit​

8. Java バックエンドとページコンテキスト​

9. 高度なサンプル：従業員プロフィール編集​

10. モードと公開状態​

11. 条件付きフィールド​

12. リモート検証とサーバーエラー​

13. 繰り返しグループ​

14. データアダプターと変更セット​

15. 下書き​

16. モデルまたは Schema から生成​

17. トラブルシューティング​