DTO中Form Layout配置复杂表单支持Tabs/Groups/Sections

Cabloy 的 Form Layout 组件正是为应对这一挑战而诞生。它允许开发者在 DTO 中定义字段在表单中的位置与层级关系，前端则依据这份配置自动渲染布局。

其核心设计理念十分清晰：Form Layout 仅专注于“字段的定位”，而字段类型、校验规则等行为逻辑，仍由原有的 schema 和表单配置独立处理。

Form Layout 的主要功能

通过 Form Layout，我们可以在 DTO 中轻松实现以下常见需求：

• 自由调整字段的显示顺序；
• 将相关字段归入带有标题的业务分组；
• 在桌面端实现多列布局，在移动端自动切换为单列；
• 将“基本信息”“培训记录”等相互独立的内容，拆分到不同的 Tab 标签页；
• 让 Create、Update、View 等不同表单场景共享统一的布局方案。

它常用的几个节点并不复杂：

• field：用于放置单个字段；
• section：将字段排列为一列或多列；
• group：将相关字段组织成一个业务分组；
• tabs / tab：将不同业务内容分配到独立的标签页中。

示例：使用 Form Layout 组织 Student 表单

以下代码片段摘自 Student Create DTO 中与 Form Layout 相关的配置。为突出布局结构，我们省略了 DTO 的外层定义、页面操作及其他字段配置。

 复制代码ZovaRender.block('basic-form:blockFormLayout', {
  formLayout: {
    children: [
      {
        type: 'tabs',
        children: [
          {
            type: 'tab',
            title: $locale('BasicInformation'),
            children: [
              {
                type: 'group',
                title: $locale('StudentProfile'),
                children: [
                  {
                    type: 'section',
                    columns: { default: 1, md: 2 },
                    children: [
                      { type: 'field', name: 'name' },
                      { type: 'field', name: 'mobile' },
                      {
                        type: 'field',
                        name: 'imageId',
                        span: { default: 1, md: 2 },
                      },
                    ],
                  },
                ],
              },
            ],
          },
          {
            type: 'tab',
            title: $locale('TrainingRecords'),
            children: [
              { type: 'field', name: 'level' },
              { type: 'field', name: 'trainingRecords' },
            ],
          },
        ],
      },
    ],
  },
});

从外到内依次解读这段代码，便能清晰理解其最终呈现的布局效果。

1. tabs 与 tab：按业务区域划分页面

最外层的 tabs 创建了一组标签页。这里有两个 tab：

• BasicInformation：基本信息；
• TrainingRecords：培训记录。

当表单包含多个彼此独立的业务区域时，Tab 标签页能帮助用户每次只聚焦当前内容。当然，字段较少时无需强行使用 Tab，直接分组通常更为直观。

2. group：为相关字段划定归属分组

在基本信息标签页中，group 的标题为 StudentProfile，它将姓名、手机号和头像统一归入“学员资料”这一共同语义下。

我们可以将 group 理解为带有标题的业务分组。联系方式、收货地址、审批信息等场景，都非常适合使用 Group 来组织。

3. section：控制响应式分栏布局

columns: { default: 1, md: 2 } 表示默认使用单列，当屏幕宽度达到 md 及以上断点时，自动切换为两列。因此，name 和 mobile 两个字段在桌面端可并排显示，在移动端则自然变为上下排列。

4. field：引用 DTO 中已定义的字段

每个 field 通过 name 属性关联 DTO schema 中的字段，例如 name。其输入控件、标题和校验规则，均沿用字段自身已有的定义。

值得留意的是 imageId 的配置：span: { default: 1, md: 2 } 表示默认单列时占一列，而在两列布局中则横跨两列。这种设置非常适合头像、备注、说明等需要独占一行的字段。

如何选择合适的布局节点

第一次配置 Form Layout 时，可以从最小结构开始尝试：

一个常见的组合策略是：Tab 划分业务区域，Group 体现业务分组，Section 处理响应式分栏，Field 放置具体字段。

不过需要提醒：切忌为了追求层级“完整”而套用所有容器。简单的表单，使用 field 即可；需要两列布局时再加 section；字段确属于同一业务块时，才考虑添加 group。

一个容易被忽略的要点

Form Layout 控制的是字段的布局位置，而非字段的可见性配置。

如果某个字段不应显示，正确的做法是在字段自身的 schema metadata 中设置可见性。仅仅不将其写入 formLayout，并不等同于隐藏该字段；因为可见字段仍可能出现在表单末尾。

总结

Form Layout 让我们可以在 DTO 中描述复杂表单的结构：

• 使用 field 决定字段顺序；
• 使用 section 实现响应式分栏；
• 使用 group 表达业务分组；
• 使用 tabs / tab 拆分独立内容。

牢记这一分工即可：DTO 描述字段结构，schema 和表单运行时负责字段的行为逻辑。 当表单字段增加或调整时，只需同步修改 DTO 中的布局配置，无需在多个页面重复维护字段的排列方式。

延伸阅读

• Form Layout Guide
• Form Guide
• Student Create DTO 示例