vaadin-form-layout

Vaadin フォームの作成

ワークフロー

進捗を見える状態に保ち、作業が途中で中断されても再開できるように、次の3つのステップをTODOとして記録してください。順番に進めてください。

Step 1 – 入力を理解して計画する

まず仕様のソースを確認します。Figma の URL を取得して調べる、スクリーンショットを読み取る、またはテキストプロンプトを解析します。

• 明確に定義された仕様（フィールドリストが明示されている場合、またはフィールドとラベルが明確なデザインの場合）：指定どおりに実装します。フィールドを勝手に追加したり、ラベルを変更したり、仕様にないコントロールを加えたりしないでください。出力は予測可能で、入力に忠実である必要があります。
• 曖昧なリクエスト（例：「顧客フォームを作成して」という、フィールドリストがないリクエスト）：計画を立てる前に、いくつかの的を絞った確認質問をします。どのフィールドとデータ型を使うか、どのようにグループ化するか、セクションを1つにするか複数にするかを確認してください。内容を黙って推測しないでください。 内容が確定したら、構成を計画してTODOに記録します。
• フィールドのリストと各フィールドのデータ型
• セクションのレイアウト — 単一セクション、縦に並べたセクション、または横に並べたセクション
• 計画した構成に最も近い参考例（下の表を参照） セクション分けの指針： フォームに複数の論理的なフィールドグループ（例：基本情報と住所）が含まれる場合は、別々のFormLayoutインスタンスに分割します。セクションごとに1つのインスタンスを使用し、それぞれのFormLayoutに列幅全体にまたがる見出しを追加します。周囲のビュー階層に合ったレベルの見出し要素を使用してください（例：ページタイトルの下にネストしたセクション見出し）。周囲のコードから適切なレベルが明確でない場合は、参考例と同様にH4をデフォルトとして使用してください。正確なレベルをわざわざ調べる必要はありません。セクションは、折り返しに対応したHorizontalLayout（幅を均等に拡大・縮小し、狭いビューポートでは1列に折り返す）で横に並べるか、VerticalLayoutで縦に並べます。

Step 2 – 参考資料を集める

計画で使用するコンポーネントが確定したら、次の作業を行います。

• テーマを特定します。 Application.javaで@StyleSheetのインポートを確認します。Aura.STYLESHEETならAura、Lumo.STYLESHEETならLumoです（テーマが見つからない場合のデフォルトもLumoです）。テーマはコンポーネントのバリアントに影響します。たとえば、横並びのラジオグループにはRadioGroupVariant.AURA_HORIZONTALまたはRadioGroupVariant.LUMO_VERTICALを使用します。
• 該当する参考例（下の表を参照）を最初から最後まで読みます。
• 使用するすべてのコンポーネントについて、FormLayoutも含めて、mcp_vaadin_get_component_java_apiでコンポーネントAPIドキュメントを取得します。メソッドのシグネチャはVaadinのバージョンによって異なります。

Step 3 – UIコードを書く

選択した参考例のパターンに従ってフォームを実装します。フォームの本体には必ずFormLayoutを使用してください。主なレイアウトの考え方：

• 自動レスポンシブ — setAutoResponsive(true)とaddFormRow(...)を使用して、最も幅の広い行から列数を推定します。利用可能な幅を埋めるには、setExpandColumns(true)およびsetExpandFields(true)と組み合わせます。幅が均一なフィールドに適しています。
• レスポンシブステップ — 自動レスポンシブの代替手段です。幅ごとのレイアウトを細かく制御する必要がある場合は、setResponsiveSteps(...)を使用して、特定のブレークポイントでの列数を明示的に定義します。
• 列スパン — form.add(field, n)に列数を渡すか、フィールドごとの列スパンを指定したFormRowを使います。
• 幅の制約 — 大きなビューポートでもフォームを読みやすく保つため、setMaxWidth／setMinWidthを設定します。
• 非対称な行 — 行内のフィールドごとに幅を変える場合は、それらをHorizontalLayoutでラップし、単一の全幅アイテムとして追加します。

例

ファイル	内容
references/horizontal-sections-form-example.md	2 セクションのエンティティフォーム。横並びの自動レスポンシブな FormLayout パネル、均等に拡張する HorizontalLayout ラッパー、HorizontalLayout.expand による非対称なフィールド行、読み取り専用フィールド、横並びの RadioButtonGroup（Aura）、デフォルト値を設定した ComboBox、ヘルパーテキスト付きの NumberField を紹介します。
references/vertical-sections-three-column-form-example.md	3 セクションの従業員フォーム。積み重ねた VerticalLayout セクション、3 列の自動レスポンシブな FormLayout、FormRow の列スパン、DatePicker、EmailField、電話番号のヘルパーテキストを紹介します。
references/compact-single-section-form-example.md	コンパクトな 1 セクションのフォーム。段階的な情報開示（CheckboxGroup によってフィールドを条件付きで表示）、動的なヘルパーテキストを備えた横並びの RadioButtonGroup、HorizontalLayout による非対称なフィールド行、アイコンのプレフィックス、リアルタイムで計算される概要ラベル、幅を制限したフォームを紹介します。
references/compact-labels-aside-form-example.md	コンパクトなラベル横配置フォーム。2 列のラベル／フィールドレイアウトを実現する setLabelsAside(true)、NumberField と ComboBox を組み合わせて単一のフォーム項目にする CustomField、文字数制限付きの TextArea、必須フィールドのインジケーター、幅を制限したフォームを紹介します。