表单的三要素：控件、数据与业务逻辑如何分工

本文不谈用哪种设计器，先谈一张表单由什么组成：控件、数据与业务逻辑，以及三者各自的元数据载体。

表单的三要素：控件、数据与业务逻辑如何分工

一、为什么先谈三要素

选设计器之前，先问一句：一张表单到底装了什么？

答案固定是三块——

《五大设计器》讲的是造车厢的车间；本文讲的是车厢里三样货怎么摆。车间可以换，货的分类不变。

低代码轨道上，三要素全部落在数据库元数据表里：

Sys_MapData (No, PTable)
  ├─ Sys_MapAttr          → 字段控件（主表/从表列）
  ├─ Sys_MapDtl           → 从表容器
  ├─ Sys_FrmAttachment    → 附件区
  ├─ Sys_GroupField       → 布局分组（可挂 Dtl / Ath）
  └─ Sys_MapExt           → 挂在字段上的扩展逻辑

二、数据维度

数据是三要素里最稳的那一层：换设计器、换皮肤，物理表结构通常不动。

2.1 三层数据：主表 · 从表 · 附件

请假演示流程里：节点表单 ND101（填写请假申请单）的 PTable 是 ND1Rpt；后续节点 ND102～ND104 往往共用同一张物理表，差异在各节点自己的 MapAttr 与权限方案——业务数据仍然是 ND1Rpt 的一行。

口诀：MapData.No 是逻辑表单 ID，PTable 才是真正 INSERT/UPDATE 的表名。 多节点可以「多张逻辑表单、一张物理表」。

2.2 字段怎么描述一列数据

每个字段是 Sys_MapAttr 的一行，三个正交维度一起定「这列是什么」：

MyDataType 常用值（与 wiki 一致）：

例如请假 demo：QingJiaRiQiCong（请假日期从）是 UIContralType=0（TB）+ MyDataType=6（日期）；QingJiaTianShu 是浮点天数；QingJiaYuanYin 是大块文本。

2.3 运行时谁去读写

• GEEntity(frmID) / GEEntityOID：按 MapData.GenerHisMap() 把 Sys_MapAttr 投影成动态 EnMap，读写 PTable。
• GEDtl：从表行，带 RefPK / FID / OID。
• 附件不走「普通列」那条路，而是 FrmAttachmentDB.RefPKVal 挂到主表主键。

从表、附件在布局上通过 Sys_GroupField.CtrlType = 'Dtl' | 'Ath' 挂到分组里——它们是容器级数据，不是普通文本框的一种 UIContralType。

2.4 数据维度小结

三、控件元素

控件回答的是：用户看见什么、点什么。

3.1 权威枚举：UIContralType

服务端定义在 数据引擎/En/EnumLab.cs，前端有对应 TS 枚举；傻瓜设计器面板还会按业务再分组。

粗算：C# 命名常量约 26 种；前端/设计器面板再加按钮、色标等扩展后约 30+。产品上「能拖进画布的基础字段」不止枚举字面量——同一个 TB，配不同 MyDataType，就是不同输入体验。

3.2 从表与附件：容器，不是「多一个 TB」

傻瓜设计器入口：

• 组件面板：Vue3/.../FoolFormDesigner/props/form/FormComponents.ts
• 拖入落库：CreateFieldFunctions.ts → 写 Sys_MapAttr
• 画布注册：components/widgets/registry.ts

3.3 字段属性页按控件分流

右键字段属性不是一张万能表：EditPageMap 按 UIContralType 打开不同 EnMap（MapAttrString / MapAttrEnum / MapAttrSFTable / 评分 / 签批 / 公文…）。控件类型决定你能配哪些扩展入口——例如外键下拉才挂「级联 ActiveDDL」，文本框才挂「Pop / TBFullCtrl」。

3.4 控件维度小结

四、业务逻辑

业务逻辑回答的是：改了 A，B 和 C 怎么办？

载体是 Sys_MapExt：挂在表单/字段上，用 ExtModel（及兼容字段 ExtType） 告诉运行时走哪条分支。CCForm 侧主解析在 OneMapAttr.vue（DealMapExtBySelect、NumberORDateChange 等）；复杂 SQL/树数据进 Sys_GenerDBSrc。

常量清单见 MapExtXmlList（MapExtXml.cs），设计器向导见 GPN_ComponentMapExt.ts。

4.1 三类最常见的逻辑

（1）级联关系 —— ActiveDDL / 级联选择器

• 场景：省 → 市 → 区；部门 → 人员；请假类型 → 需不需要上传证明。
• 配置：外键/枚举字段右键 → GPE_ActiveDDL；AttrOfOper 为驱动字段，AttrsOfActive 为被刷新字段。
• 运行时：选中变化 → GetActionDLLData → 刷新下游 DDL。
• 一键组合：向导里的「省份/城市/区县」级联，主字段存编号链，影子字段存名称链（见 GPN_ComponentMapExt.CityDesc）。

（2）计算公式 —— AutoFull / ReqDays

• 场景：单价 × 数量 = 小计；请假日期从/到 → 天数。
• 小计向导 XiaoJi：自动建名称/单价/数量/小计四列，并写入：

ExtModel = AutoFull
AttrOfOper = {前缀}Sum
Tag = @{前缀}Unit*@{前缀}Num

• 日期差 ReqDays：向导 DTFromToDD（页面占位名就是「请假日期」）创建从、到、天数字段，并挂 ExtModel=ReqDays。
• 从表聚合：AutoFullDtlField 把明细列汇总回主表。

产品提示词与 AI 工具里也沿用同一套表达式习惯：@单价*@数量——逻辑写在元数据里，而不是散落在页面脚本。

（3）Pop 弹窗选值与回填 —— Pop / PopFullCtrl / TBFullCtrl

• 场景：选代理人、选物资、选合同号，带回编号、名称及相关字段。
• DoWay 形态：树（PopBranches / PopTreeEns）、分组列表（PopGroupList）、表格（PopTable）、自定义 URL（PopSelfUrl）等。
• 运行时：ExtModel 为 Pop / TBFullCtrl / DDLFullCtrl 时走 GetFullData，再 ChangeParentAttr(..., 'FullData') 回填其它控件。
• 文本自动完成：输入工号带出姓名、电话、邮件——向导「人员输入」一类，本质仍是 MapExt + 数据源。

4.2 其它常用 ExtModel（速查）

4.3 业务逻辑小结

高代码轨道另有 EnMapExt（useMapExtHandler.ts），语义相近（联动、自动计算、弹窗填充），配置面在实体 EnMap 上——与低代码 Sys_MapExt 同属 数据引擎 家族，配置入口不同。

五、三要素怎么拧在一张请假单上

用「请假」把三层钉死（对照演示包与组合向导）：

同一套三要素，换到合同/检验单只是字段更多、逻辑更密，不是另一套理论：合同用章节设计器排「章—节」，检验用 VSTO 扛公式——MapAttr / PTable / MapExt 仍然是三根柱子。

六、和姊妹文档怎么衔接

选型顺序建议：

1. 先想清数据（主从附件、主键怎么挂）；
2. 再铺控件（字段类型与容器）；
3. 把交互收进 MapExt；
4. 最后才选设计器——先用经典，装不下再换车厢。

七、小结

1. 控件是 Sys_MapAttr（外加 Dtl/Ath 容器）；形态看 UIContralType，类型看 MyDataType，字典/外键看 LGType。
2. 数据是 MapData.PTable + 从表 RefPK + 附件 RefPKVal；逻辑表单 ID 可以多个，物理表可以共用。
3. 业务逻辑是 Sys_MapExt.ExtModel：级联、AutoFull、Pop/回填、装载填充、显隐与校验。
4. 请假单是最小完整样例；合同、检验、公文只是三要素的密度与呈现车间不同。

延伸阅读

• 《该表单引擎：表单的业务逻辑设计》：MapExt 主表/从表逻辑专篇（AutoFull、Pop、级联）。
• 《该表单引擎：表单元素的分类与实现》：主表 / 从表 / 附件 / 扩展控件四层切片。
• 《表单引擎在应用系统中的位置与作用》：同一引擎在流程 / 实体 / 单据 / 活动中的四种角色。
• 《表单引擎三大范式与双轨实现》：文件 / 数据库 / 规则三种范式，低代码与高代码双轨。
• 《五类表单设计器：应用场景与设计特征》：请假 / 公文 / 合同与申报 / 检验检测如何选车间。
• 课程 A 第 02 讲：表单本质——车厢、货物与动力系统。

本文依据当前仓库 数据引擎 与 Vue3 表单运行时静态整理；具体菜单文案与向导页以你部署的版本为准。