表单配置

表单的创建、设计与管理，以及表单在工作区中的组织方式。

概述

在 开发中心 → 对象设置 → 表单 中可以管理某个实体对象下的所有表单。表单（Form）用于配置数据的录入与展示界面，它把实体对象的字段以可视化的方式编排成特定的布局与样式。

表单与对象、字段的关系如下：

一个表单必须归属于一个实体对象（MetaObjectId），表单可用的字段来自该对象及其 Lookup 关联字段。
表单只负责界面编排，字段的数据类型、验证规则、渲染方式等仍由字段配置决定。
同一个对象可以创建多个表单，分别服务于不同的业务场景（如「新增表单」「编辑表单」「详情表单」）。

定位说明

表单是纯配置数据（布局 + 属性），本身不承载业务数据。使用表单时的数据读写由平台接口或平台默认处理逻辑（DefaultQuerySingle / DefaultAdd / DefaultEdit）完成，表单只负责界面呈现。

配置项

表单列表用于维护对象下的表单，表单的基础属性如下：

配置项	说明
表单名称	表单显示名称，必填，用于在列表中识别
表单标题	表单渲染时展示的标题，留空时回退为表单名称
描述	表单用途说明，可选

表单的其余配置（布局方向、渲染宽度、接口绑定、提交后行为、按钮文案等）在表单设计器 → 表单设置中完成，详见表单全局属性。

创建流程

表单通过以下步骤创建与完善：

进入对象设置，选择表单页签，列表展示当前对象下的全部表单。
点击 创建表单，填写表单名称、标题与描述后保存。
系统自动在新窗口打开该表单的表单设计器。
从左侧组件库拖拽布局容器与字段到画布，完成界面布局。
点击 保存布局 持久化设计结果，点击 弹窗预览 预览渲染效果。

创建后自动打开设计器

只有「创建表单」操作会在成功后自动打开设计器；编辑表单只修改名称、标题与描述，仍停留在列表。

表单设计器

表单设计器是表单配置的核心，采用「左侧组件库 + 中间画布 + 右侧属性面板」的三栏结构，支持拖拽布局、多列容器、页签/步骤/分段切换、字段属性配置、脚本联动与预览。

设计器的完整使用方法请参阅表单设计器。

下一步

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

属性明细

以下内容面向技术实现与 AI 检索，逐个说明表单实体的属性、类型与存储。

表单属性表

属性名	类型	含义	取值/存储值
`_id`	string(GUID)	表单主键	例：`8c1f9b2e-...`
`AppId`	string(GUID)	所属应用	继承自 `AppEntityBase`
`MetaObjectId`	string(GUID)	所属实体对象	表单字段的来源
`Name`	string	表单名称	必填
`Title`	string	表单标题	可为空
`Description`	string	表单描述	可为空
`Customized`	bool	是否被自定义过	内置表单被修改后为 `true`
`CustomCreated`	bool	是否由用户自定义创建	用户新建为 `true`
`LayoutType`	`MetaFormLayoutEnum`	表单项布局方式	见「枚举定义」
`RenderWidthType`	`RenderWidthTypeEnum`	渲染宽度方式	见「枚举定义」
`RenderWidth`	string	自定义渲染宽度	仅自定义时生效，支持 `%`/`px`
`GetInterfaceId`	string(GUID)	详情页加载数据接口	覆盖默认查询逻辑
`SaveInterfaceId`	string(GUID)	新增保存接口	覆盖默认新增逻辑
`EditInterfaceId`	string(GUID)	编辑保存接口	覆盖默认编辑逻辑
`AfterSubmitAction`	`AfterSubmitActionEnum`	提交后动作	见「枚举定义」
`MetaPageId`	string(GUID)	提交后跳转的页面	`AfterSubmitAction = 1` 时生效
`CustomPageAddress`	string	提交后跳转的自定义地址	`AfterSubmitAction = 9` 时生效
`RowSpace`	int	外层元素垂直间距	默认 `8`，范围 0–30
`HideOkButton`	bool	是否隐藏 [确定] 按钮	`true`/`false`
`OkButtonText`	string	[确定] 按钮文案	留空用系统默认值
`OkButtonAction`	`MetaFormOkButtonActionEnum`	[确定] 按钮动作	见「枚举定义」
`HideCancelButton`	bool	是否隐藏 [取消] 按钮	`true`/`false`
`CancelButtonText`	string	[取消] 按钮文案	留空用系统默认值
`IsQuickInitialization`	bool	是否快速初始化	系统在快速初始化表单时置位
`Layout`	`List<WidgetItem>`	表单设计器布局	JSON，见表单设计器
`Properties`	`MetaFormProperties`	自定义扩展属性	见「MetaFormProperties」

枚举定义

public enum MetaFormLayoutEnum
{
    Vertical = 0,    // 垂直布局
    Horizontal = 1,  // 水平布局
}

public enum RenderWidthTypeEnum
{
    Default = 0,  // 默认
    Custom = 9,   // 自定义
}

public enum AfterSubmitActionEnum
{
    None = 0,
    RedirectToDetailPage = 1,   // 保存后跳转到详情页，需要配置详情页 id
    RedirectToResult = 8,       // 跳转到结果页
    RedirectToCustomPage = 9,   // 跳转到自定义页面
}

public enum MetaFormOkButtonActionEnum
{
    Submit = 0,               // 提交表单
    SubmitThenContinue = 1,   // 提交并继续
    CloseForm = 2,            // 关闭表单
}

MetaFormProperties

属性名	类型	含义
`AddInitDataInterfaceId`	string(GUID)	新增表单预置数据接口
`EditInitDataInterfaceId`	string(GUID)	编辑表单预置数据接口
`HideEmptyFieldInDetail`	bool	详情模式下是否隐藏空字段

通用实体属性

表单继承自 AppEntityBase → EntityBase，同时具备以下通用属性：

属性名	类型	含义
`IsDeleted`	bool	是否已删除（逻辑删除）
`CreatedBy` / `CreatedTime`	string / datetime	创建人 / 创建时间
`ModifiedBy` / `ModifiedTime`	string / datetime	修改人 / 修改时间
`Organization`	string(GUID)	所属组织

存储示例

表单存储在数据表 system_metaform 中，Layout 与 Properties 以 JSON 字符串列存储：

{
  "_id": "8c1f9b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "AppId": "9f1c0b2e-2d3a-4e6f-9c11-0f7a5b8d2e10",
  "MetaObjectId": "3b7d1a2c-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
  "Name": "图书新增表单",
  "Title": "新增图书",
  "Description": "图书基础信息录入",
  "Customized": false,
  "CustomCreated": true,
  "LayoutType": 0,
  "RenderWidthType": 0,
  "RenderWidth": "",
  "GetInterfaceId": "",
  "SaveInterfaceId": "",
  "EditInterfaceId": "",
  "AfterSubmitAction": 0,
  "MetaPageId": "",
  "CustomPageAddress": "",
  "RowSpace": 8,
  "HideOkButton": false,
  "OkButtonText": "",
  "OkButtonAction": 0,
  "HideCancelButton": false,
  "CancelButtonText": "",
  "Properties": {
    "AddInitDataInterfaceId": "",
    "EditInitDataInterfaceId": "",
    "HideEmptyFieldInDetail": false
  },
  "Layout": [
    {
      "id": "b1a2c3d4-...",
      "uid": "5a0f3c1e-9b8d-4f6a-9c2e-7d1b4a8e6f3d",
      "dragType": "Row",
      "originalType": "Row",
      "widgetType": "Row",
      "widgetTypeName": "基础容器",
      "children": [
        { "id": "c1a2...", "uid": "7b9a905e-...", "widgetType": "Column", "children": [] }
      ]
    }
  ],
  "IsDeleted": false,
  "CreatedBy": "admin",
  "CreatedTime": "2026-01-05T09:12:30"
}

接口	说明
`GET /api/MetaForm/Get`	获取表单详情（含 `Layout`）
`POST /api/MetaForm/Create`	新建表单
`POST /api/MetaForm/Edit`	编辑表单基础属性
`POST /api/MetaForm/SaveLayout`	保存表单设计器布局
`POST /api/MetaForm/Copy`	基于现有表单复制出一个新表单
`POST /api/MetaForm/GetList`	分页获取对象下的表单列表

概述​

配置项​

创建流程​

表单设计器​

下一步​

属性明细​

表单属性表​

枚举定义​

MetaFormProperties​

通用实体属性​

存储示例​

相关接口​

概述

配置项