vaadin-form-layout

Vaadin 表单创建

工作流

将以下三个步骤记为 TODO，让进度保持可见，并确保工作在中途被打断后可以继续。按顺序完成这些步骤。

步骤 1 – 理解输入并制定计划

先处理规范来源：获取并检查 Figma URL、读取截图，或解析文本提示词。

• 定义明确的规范（明确列出字段，或设计中字段和标签清晰）：严格按规范实现。不要自行添加字段、重命名标签，或添加规范中未要求的控件。输出应可预测，并忠实于输入。
• 模糊的请求（例如，没有字段列表的“创建一个客户表单”）：先提出几个有针对性的澄清问题，再制定计划——询问字段及其数据类型、字段如何分组，以及表单应为单个区块还是多个区块。不要默默猜测表单内容。 确定表单内容后，规划结构，并将其记录在 TODO 中：
• 字段列表以及每个字段的数据类型；
• 区块布局——单个区块、垂直堆叠的区块，或并排的水平区块；
• 与计划结构最匹配的参考示例（见下表）。 **区块划分指南：**当表单涵盖多个逻辑字段组（例如基本信息和地址）时，将它们拆分为多个 FormLayout 实例——每个区块使用一个实例，并在其中添加一个横跨整列宽度的标题。选择的标题级别应符合所在视图层级（例如，在页面标题下嵌套一个区块标题）。如果无法从周围代码中判断合适的级别，默认使用 H4，如参考示例所示——不要特意查找确切级别。使用可换行的 HorizontalLayout 将区块并排排列（同等扩展和收缩，在窄视口下换为单列），或使用 VerticalLayout 将其垂直堆叠。

步骤 2 – 收集参考资料

确定计划中使用的组件后：

• **确认主题。**检查 Application.java 中的 @StyleSheet 导入：Aura.STYLESHEET → Aura，Lumo.STYLESHEET → Lumo（未找到主题时也默认使用 Lumo）。主题会影响组件变体，例如水平单选组使用 RadioGroupVariant.AURA_HORIZONTAL 或 RadioGroupVariant.LUMO_VERTICAL。
• 从头到尾阅读匹配的参考示例（见下表）。
• 使用 mcp_vaadin_get_component_java_api 获取所有要使用的组件的 API 文档，包括 FormLayout——不同 Vaadin 版本的方法签名有所不同。

步骤 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	双分区实体表单，包含并排且自动响应的 FormLayout 面板、等比例扩展的 HorizontalLayout 包装器、通过 HorizontalLayout.expand 实现的不对称字段行、只读字段、水平排列的 RadioButtonGroup（Aura）、带默认值的 ComboBox、带辅助文本的 NumberField
references/vertical-sections-three-column-form-example.md	三分区员工表单，包含堆叠的 VerticalLayout 分区、自动响应的三列 FormLayout、FormRow 跨列、DatePicker、EmailField、电话号码辅助文本
references/compact-single-section-form-example.md	紧凑的单分区表单，包含渐进式披露（CheckboxGroup 有条件地显示字段）、带动态辅助文本的水平 RadioButtonGroup、通过 HorizontalLayout 实现的不对称字段行、图标前缀、实时计算的摘要标签、受限的表单宽度
references/compact-labels-aside-form-example.md	标签置于侧边的紧凑表单，通过 setLabelsAside(true) 实现两列标签/字段布局；通过组合 NumberField 和 ComboBox，使用 CustomField 将两者合并为单个表单项；带字符数限制的 TextArea、必填字段指示器、受限的表单宽度