表单设计器

通过拖拽方式编排表单界面：布局容器、字段排布、属性配置与预览。

概述

表单设计器是表单配置的核心界面，用于把实体对象的字段拖拽编排成最终的录入/展示界面。设计器采用「左侧组件库 + 中间画布 + 右侧属性面板」的三栏结构：从左侧拖入组件到中间画布，选中组件后在右侧抽屉中配置其属性，最后保存布局。

设计器的配置结果保存在表单的 Layout 属性中（一组嵌套的 WidgetItem），每次点击保存会整体写回。

配置项

设计器界面的功能区域与操作如下：

区域/操作	说明
组件搜索	左侧组件库顶部输入框，按组件名称关键字过滤
组件库分类	布局组件、表单字段、图表组件、UI 组件、其他组件等可折叠分组
画布	中间区域，根容器，所有组件最终都拖拽到这里
预览模式/编辑模式	标题栏左侧开关，切换预览模式可直接查看最终渲染效果
弹窗预览	以弹窗方式预览表单（使用表单全局的渲染宽度）
表单设置	打开表单全局属性抽屉，详见表单全局属性
保存布局	保存当前画布布局到表单 `Layout`
组件工具栏	选中组件后在组件右上角浮动显示，支持上移、下移、复制组件、移除此组件、属性设置
拆分列 / 删除列	布局列上的操作，用于调整多列容器的列数

快速打开属性设置

单击组件选中，或在组件上双击可直接打开右侧属性设置抽屉。

界面布局

设计器从上到下、从左到右分为以下部分：

左侧组件库：以折叠分组展示可拖拽的组件，已被单例限制使用的组件会置灰。
中间画布：表单根容器，顶部以 <Form> 包裹全部子组件，表单的布局方向（LayoutType）在此生效。
右侧属性面板：抽屉形式，标题为当前选中组件的类型名称；抽屉右上角提供上移、下移、复制、删除操作。
标题栏：展示表单名称、最近修改时间与「跳转到对象设置」入口。

拖拽规则

设计器采用树形布局模型，不同容器接受的组件类型不同：

容器	可接受的直接子组件
根容器（画布）	基础容器（`Row`）
布局列（`Column`）	基础容器（`Row`）、任意普通组件

因此实际搭建顺序为：先在画布放入基础容器（自动带一列），再把字段、页签、UI 组件等拖入布局列中。

拖拽时画布会显示插入位置指示线，落点以最后一次指针位置为准。
组件在布局内按 id 唯一标识；复制会生成新的 id。
布局列（Column）是结构性容器，本身不可拖动、不可删除，只能配置属性，可通过「拆分列 / 删除列」调整所在行。

布局容器组件

布局容器用于组织表单结构，均从左侧「布局组件」分类拖入。

基础容器

多列布局的基础容器，支持动态列数与列宽调整。

配置项	说明
列间距	行组件中多个列之间的间距，默认 5
单元格宽度	拖拽滑块调整各列宽度（以 24 栅格为基准）
自适应列数	开启后按设备宽度自动适应列数，关闭后所有设备使用固定列数

在画布中把鼠标移到基础容器上，会出现列分隔线，拖动即可调整列宽；在布局列上使用「拆分列」可增加列数。

布局列

基础容器中的单列容器，用于承载具体组件。

配置项	说明
子元素间距	子元素在单元格中的纵向间距，默认 5
布局方式	`vertical`（垂直）/ `horizontal`（水平）
对齐方式	`default` / `start`（左对齐）/ `end`（右对齐）/ `center`（居中）

Tab 容器

多页签布局，每个页签是一个布局列，页签内可继续放置组件。

配置项	说明
配置页签	排序、重命名、设置默认激活页签、删除页签、添加页签
页面部件数据源接口	选择数据源接口，可动态提供页签配置与标题

Step 容器

多阶段布局，每个步骤是一个布局列，常用于分步录入表单。

配置项	说明
展示类型	`default` / `navigation`（导航）/ `inline`（内联）/ `panel`（面板）/ `dot`（点状）
标签放置位置	`horizontal`（水平）/ `vertical`（垂直）
大小	`default` / `small`（小号）
方向	`horizontal`（水平）/ `vertical`（垂直）
编辑步骤	排序、设置图标与标题、设置副标题与描述、删除步骤、添加步骤

分段控制器

分段切换布局，每个分段是一个布局列。

配置项	说明
大小	`large`（大）/ `middle`（中）/ `small`（小号）
形状	`default` / `round`（圆角）
对齐方式	`left`（左对齐）/ `center`（居中）/ `right`（右对齐）/ `block`（拉伸）
配置分段	排序、设置图标与标题、设置默认激活分段、删除分段、添加分段
页面部件数据源接口	选择数据源接口，可动态提供分段配置与标题

组件操作

选中组件后，组件右上角出现浮动工具栏：

操作	说明
上移 / 下移	在同一容器内调整组件顺序
复制组件	复制当前组件及其子组件到同级
移除此组件	从布局中移除当前组件
属性设置	打开右侧属性面板
拆分列	仅布局列可用，在其所在行中拆出一列
删除列	仅布局列可用，删除该列（列内元素一并删除）

预览与保存

预览模式：标题栏左侧开关，打开后画布以最终渲染效果展示（Switch 切换「预览模式 / 编辑模式」）。
弹窗预览：以弹窗形式预览表单，弹窗宽度由表单全局的「渲染宽度」决定，详见表单全局属性。
保存布局：点击后需二次确认（「是否保存当前布局？」），确认后把画布布局整体写入表单并提示「操作成功」。

下一步

表单字段属性 - 设计器中每个字段的属性配置
表单全局属性 - 布局方向、渲染宽度、接口绑定、提交后行为
表单脚本 API - 字段脚本与联动逻辑

组件属性明细

以下内容面向技术实现与 AI 检索，逐个说明设计器布局树与容器组件属性的存储格式。

WidgetItem 结构

设计器布局 Layout 是一组嵌套的 WidgetItem：

属性名	类型	含义
`id`	string	布局内唯一标识，拖拽/复制时重新生成
`uid`	string	组件类型固定标识，用于判断组件是否已被使用
`dragType`	string	拖拽分类
`originalType`	string	真实分类
`widgetType`	string	组件类型（如 `Row`、`Column`、`Tab`、`FormItem`）
`widgetTypeName`	string	组件名称
`children`	`WidgetItem[]`	子组件
`meta`	`Record<string,string>`	组件属性，值统一存为字符串

meta 均为字符串

所有组件属性（含布尔值）都以字符串形式存储在 meta 中，例如 FixedColumns: "true"、IsHide: "true"。

根容器接受规则

export const CONTAINER_ACCEPT_RULES = {
    root: [WidgetType.Row],                    // 画布只接受基础容器
    column: [WidgetType.Row, WidgetType.Widget], // 布局列接受容器与普通组件
};

容器组件 meta 属性

组件	meta 属性名	类型	含义	取值/存储值
基础容器 `Row`	`ColumnSpace`	string(int)	列间距	默认 `"5"`
基础容器 `Row`	`ColumnsWidth`	string	列宽分割点	逗号分隔，如 `"12"` 表示两列各 12
基础容器 `Row`	`FixedColumns`	string(bool)	强制固定列数展示	`"true"`（所有设备固定列宽）/ `"false"`（默认，按设备宽度自适应）
布局列 `Column`	`ItemSpace`	string(int)	子元素间距	默认 `"5"`
布局列 `Column`	`LayoutType`	string	布局方式	`"vertical"` / `"horizontal"`，默认 `"vertical"`
布局列 `Column`	`Align`	string	对齐方式	`"default"` / `"start"` / `"end"` / `"center"`
Tab 容器 `Tab`	`DefaultActiveTab`	string	默认激活页签	子页签的 `id`
Tab 容器 `Tab`	`MetaInterfaceId`	string(GUID)	页面部件数据源接口	接口 id
Tab 子页签	`Title`	string	页签标题	文本
Step 容器 `Step`	`DisplayType`	string	展示类型	`"default"` / `"navigation"` / `"inline"` / `"panel"` / `"dot"`
Step 容器 `Step`	`LabelPlacement`	string	标签放置位置	`"horizontal"` / `"vertical"`
Step 容器 `Step`	`Size`	string	大小	`"default"` / `"small"`
Step 容器 `Step`	`Orientation`	string	方向	`"horizontal"` / `"vertical"`
Step 子步骤	`Icon`	string	步骤图标	图标标识串
Step 子步骤	`Title`	string	步骤标题	文本
Step 子步骤	`SubTitle`	string	步骤副标题	文本
Step 子步骤	`Description`	string	步骤描述	文本
分段 `Segmented`	`Size`	string	大小	`"large"` / `"middle"` / `"small"`
分段 `Segmented`	`Shape`	string	形状	`"default"` / `"round"`
分段 `Segmented`	`Alignment`	string	对齐方式	`"left"` / `"center"` / `"right"` / `"block"`
分段 `Segmented`	`DefaultActiveSegment`	string	默认激活分段	子分段的 `id`
分段 `Segmented`	`MetaInterfaceId`	string(GUID)	页面部件数据源接口	接口 id
分段子项	`Icon`	string	分段图标	图标标识串
分段子项	`Title`	string	分段标题	文本
通用	`WidgetTypeName`	string	组件名称	只读展示

存储示例

一个「基础容器（2 列）+ 页签」的布局片段：

[
  {
    "id": "row-1",
    "uid": "5a0f3c1e-9b8d-4f6a-9c2e-7d1b4a8e6f3d",
    "widgetType": "Row",
    "widgetTypeName": "基础容器",
    "meta": { "ColumnSpace": "5", "ColumnsWidth": "12" },
    "children": [
      {
        "id": "col-1",
        "uid": "7b9a905e-83d4-452b-83c8-694a3e0935e3",
        "widgetType": "Column",
        "meta": { "ItemSpace": "5", "LayoutType": "vertical", "Align": "default" },
        "children": []
      },
      {
        "id": "col-2",
        "uid": "7b9a905e-83d4-452b-83c8-694a3e0935e3",
        "widgetType": "Column",
        "meta": { "ItemSpace": "5", "LayoutType": "vertical", "Align": "default" },
        "children": [
          {
            "id": "tab-1",
            "uid": "f8c226b6-7b98-45a8-8c71-abeb21e2941a",
            "widgetType": "Tab",
            "meta": { "DefaultActiveTab": "tab-item-1" },
            "children": [
              { "id": "tab-item-1", "widgetType": "Column", "meta": { "Title": "基本信息" }, "children": [] }
            ]
          }
        ]
      }
    ]
  }
]

画布渲染参数

设计器画布以统一的 <Form> 包裹，表单实例参数如下：

参数	取值	说明
`layout`	`LayoutType === 1 ? 'horizontal' : 'vertical'`	由表单全局属性的 `LayoutType` 决定
`size`	`'middle'`	表单控件尺寸
`title`	`Title ?? Name`	标题，`Title` 为空时回退为 `Name`

概述​

配置项​

界面布局​

拖拽规则​

布局容器组件​

基础容器​

布局列​

Tab 容器​

Step 容器​

分段控制器​

组件操作​

预览与保存​

下一步​

组件属性明细​

WidgetItem 结构​

根容器接受规则​

容器组件 meta 属性​

存储示例​

画布渲染参数​

概述

配置项