表单元素的分类与实现：主表、从表、附件与扩展控件驰骋BPM驰骋低代码低代码工作流引擎- 惊觉

表单元素的分类与实现：主表、从表、附件与扩展控件

一、概述

表单的本质是两件事：展示数据与采集数据。这两件事决定底层逻辑；元素怎么分类，则决定设计器面板怎么摆、元数据怎么存、运行时怎么渲染。

驰骋把一张低代码表单上的「可设计元素」按数据载体分成四层：

层	装什么	元数据主表	设计器入口
主表数据	一行业务主记录上的字段	`Sys_MapAttr`（`FK_MapData`=主表）	「基础字段」`inputGroup`
从表数据	多行明细	`Sys_MapDtl` + 从表自己的 `MapAttr`	「附件/从表」→ 从表
附件	文件 / 图片	`Sys_FrmAttachment`（+ 字段级 `AthShow`）	「附件/从表」→ 字段附件 / 表格附件 / 图片
字段扩展控件	评分、手写、签批、公文…	仍是 `Sys_MapAttr`，高编号 `UIContralType`	「通用 / 附件」扩展项 + 组合向导

与《表单三要素》的关系：三要素讲控件 · 数据 · 逻辑；本文讲主表 · 从表 · 附件 · 扩展——同一车厢的两种切片。逻辑类（级联、Pop、AutoFull）不另开一章，它们挂在字段上的 Sys_MapExt 里，见三要素文档。

起点	关系	落点
表单主记录（`Sys_MapData` / `PTable`）	承载	主表字段 `Sys_MapAttr`
表单主记录（`Sys_MapData` / `PTable`）	承载	从表 `Sys_MapDtl`
表单主记录（`Sys_MapData` / `PTable`）	承载	附件 `Sys_FrmAttachment`
从表	列定义	从表列 `MapAttr`
主表字段	换一种控件	扩展控件（高编号 `UIContralType`）
主表字段	加一层行为	`Sys_MapExt` 逻辑

运行时主链（经典表单）：FrmGener → FrmFool* → MapAttrForm → OneMapAttr；从表走 DtlComponent / DtlCard；附件块走 Ath.vue。

二、主表数据

主表数据 = 主表物理行上的一列列字段。每列是 Sys_MapAttr 一行，由三个维度共同描述（详见三要素文档）：

维度	字段	作用
控件形态	`UIContralType`	TB / DDL / Radio / Check…
存储类型	`MyDataType`	字符串 / 整型 / 日期 / 金额…
逻辑类型	`LGType`	普通 `0` / 枚举 `1` / 外键 `2`

2.1 分类（对应设计器「基础字段」）

大纲里的「文本框、下拉框、单选、选择框」，在代码里展开为：

用户说法	设计器项（`FormComponents.inputGroup`）	典型落库
文本框	文字、大块文字、整数、数值、金额、日期、日期时间	`UIContralType=TB(0)` + 不同 `MyDataType`
下拉框	枚举下拉、外键下拉	`DDL(1)` + `LGType=Enum/FK` + `UIBindKey`
单选按钮	单选（enumsRadio）	`RadioBtn(3)` + 枚举
选择框	开关（布尔）、多选（enumsCheckbox）	`CheckBok(2)`；布尔用 `MyDataType=AppBoolean`

创建实现：CreateFieldFunctions.ts 中 createBasicTextField / createBasicDateField / createBasicBooleanField 等 → INSERT Sys_MapAttr。渲染：FrmEnd.useKeyOfEnType() 综合 MyDataType + UIContralType + mapExts 决定模板分支，再由 OneMapAttr.vue 画出具体控件。

2.2 实现要点

同一个 TB，配不同 MyDataType，就是不同输入体验（日期控件 ≠ 另起一种 UIContralType）。
下拉 / 单选 / 多选的数据来源不在控件枚举里，而在 LGType + UIBindKey（枚举进 Sys_Enum*，外键进 Sys_SFTable）。
组合字段 / Pop / 文本补全会出现在「实体单据引用」面板，但落库仍是主表文本字段 + Sys_MapExt——属于主表字段的行为增强，不是第四种主表数据类型。

2.3 主表小结

你要采的	优先拖	别忘了配
姓名、事由	文字 TB	长度、必填
请假天数、金额	数值 / 金额	小数位、AutoFull
请假类型	单选或枚举下拉	枚举字典
所属部门	外键下拉	SFTable / 级联

三、从表数据

从表 = 挂在主表下的多行明细。元数据：Sys_MapDtl（FK_MapData→主表，PTable→明细物理表）；列定义仍是 Sys_MapAttr，只是 FK_MapData 等于从表 No。布局上通过 Sys_GroupField.CtrlType='Dtl' 占一块区域。行键：OID + RefPK → 主表主键（流程里常为 WorkID）。

设计器：「附件/从表」→ 从表(子表) → createSlavaTable。

3.1 展示模式：`ListShowModel`（`GPE_ListShowModel`）

从表不只是「一张普通表格」。产品按 MapDtl.ListShowModel 分成三组：

（1）常规模式

值	名称	说明
0	表格（默认）	大纲说的「通用表格」；标准行列编辑
1	卡片模式	每条明细一张卡；保存后常切 `EditModel=1`（经典表单弹卡编辑）
2	自定义 URL	自研展现页，数据仍写入当前从表

另有 EditModel：0 表格内编辑 / 1 经典表单卡片编辑——管的是「怎么改行」，与「怎么列出来」正交。

（2）报表模式（交叉采集 / 展现）

值	名称	字段结构要求	维度习惯
3	2 维表	2 个外键或枚举 + 1 个数值	左=第 1 维，头=第 2 维
4	3 维表（左）	3 个外键或枚举 + 1 个数值	左侧为第 1 维
5	3 维表（上）	同上	上方为第 1 维

适用：按「年级 × 政治面貌」、多维指标矩阵等做采集或展示；存储仍是扁平从表行（维度字段 + 数值），交叉是展现算法。

（3）固定行表格

值	名称	典型场景
6	损益表模式	左树目录 + 本期 / 基期两列数值
7	大类小类	大类小类交叉

3.2 实现要点

从表是容器，不是 UIContralType；容器里的每一列才是控件。
运行时：DtlComponent.vue → 表格 Dtl.vue 或卡片 DtlCard.vue；卡片/单元格内字段仍走 OneMapAttr。
复杂计算装不下时用 自定义 URL，但不要另起一套存储——继续写当前 MapDtl.PTable。
VSTO 场景另有 VSTOEditModel（Excel 侧编辑从表），与 Web ListShowModel 并列，不互相替代。

3.3 从表小结

场景	建议模式
报销明细、行程列表	通用表格 `0`
字段多、一行编辑重	卡片 `1`
矩阵填报（两维/三维）	2 维 / 3 维表
财务本期对比	损益表 `6`
强定制交互	自定义 URL `2`

四、附件

附件解决的是：非结构化文件如何挂到表单实例上。配置在 Sys_FrmAttachment；文件行在 Sys_FrmAttachmentDB（RefPKVal 挂主表/从表主键）。

4.1 上传类型：`AttachmentUploadType`（`EnumAth.cs`）

枚举	产品转义	设计器对应	形态
Single	字段附件（历史上称单附件）	「字段附件」`appendix-field` → `createAthField`	主表某一列上的附件；常伴 `UIContralType=AthShow(6)`
Multi	表格附件（多附件）	「表格附件」→ `createAthTable` + `GroupField.CtrlType=Ath`	独立附件区，多文件列表（`Ath.vue`）
Specifically	指定的	特殊绑定	按业务指定上传对象

文案对照：FrmAttachmentExt.UploadTypeT —— Multi→「多附件」，Single→「单附件」。设计器面板用「字段附件 / 表格附件」更贴实现。

4.2 图片附件

设计器：「图片」→ createImgAth
控件：UIContralType=FrmImgAth(12)，可配 PicUploadType（相册或仅拍照等）
与普通 Ath 分流：偏图片预览与移动端拍照，仍落附件库体系

另有 写字板（HandWriting=8）在附录分组里，本质是手写图像类附件扩展，见下一节。

4.3 实现要点

层	字段附件（Single）	表格附件（Multi）
布局	行内一列	`GroupField` 一整块
MapAttr	通常有 AthShow 字段行	容器为主，不依赖普通 TB
主键习惯	`FK_FrmAttachment + '_' + PK`	GUID 等多文件主键
保存方式	`AthSaveWay`（IIS / FTP / DB…）两侧共用	同左

API 侧：CCFormAPI.CreateOrSaveAthMulti / 单附件创建路径分别写 UploadType=Multi/Single。

4.4 附件小结

需求	选
「合同扫描件」挂在字段旁	字段附件
「本单所有证明材料」一个列表	表格附件（多附件）
现场拍照、证件照	图片附件
手签确认	写字板（扩展控件）

五、字段扩展控件

扩展控件 = 仍是主表（或从表）上的 MapAttr 字段，但 UIContralType 不再是普通 TB/DDL，而是专用组件。设计器创建函数集中在 CreateFieldFunctions / EditPageMap；运行时由 OneMapAttr 的 isScore / isSignCheck / isGovDocFile 等分支接管。

5.1 常见扩展清单（按代码补全）

控件	`UIContralType`	设计/属性入口	典型用途
评分	101 Score	`ExtScore` / `universal-rate`	满意度、质量打分
写字板 / 手写签名	8 HandWriting	`createHandWriting`	签收、手签确认
签批组件	14 SignCheck	`SignCheck`	节点意见区旁的签批
评论组件	15 FlowBBS	MapAttrFlowBBS	表单内讨论
公文正文	110 GovDocFile	`MapAttrGovDocFile`	正文文件
发文字号 / 收文字号	17 / 170	DocWord*	公文文号
流程进度图	50 JobSchedule	`ExtJobSchedule`	进度可视化
轨迹图	62 FrmFlowTrack	（服务端枚举）	流转轨迹
关联流程	200 FlowRefLink	FlowRefLink	引用其它流程实例
定位 / 地图	16 Location / 4 MapPin	ExtMap / Fixed	外勤打卡、选点
录音 / 拍照	5 MicHot / 7 MobilePhoto	移动端为主	现场取证
身份证	13 IDCard	MapAttrCard	证号识别/结构化
大块说明 HTML	60 BigText / FrmHtml	`createHTML`	说明性图文，非录入
超链接 / 按钮	9 HyperLink / 18 Btn	ExtLink / FrmBtn	跳转、触发动作
图片（展示）	11 FrmImg	通用图片	装饰/示意图
二维码	—（常为 MapExt `QRCode`）	`GPE_QRCode`	扫码打开/展示

评分、签批等在 EditPageMap 里各自打开专用属性页（如 ExtScore、SignCheck），不要用普通文本框属性页硬改。

5.2 与「逻辑扩展」的边界

	字段扩展控件	逻辑类 MapExt
改什么	换成另一种控件	在原控件上加行为
例子	评分、手写、公文	级联、AutoFull、Pop、填充从表
主存	`MapAttr.UIContralType`	`Sys_MapExt.ExtModel`

Pop、文本自动完成在设计器「实体单据引用」里，实现上仍是文本字段 + MapExt，归入逻辑，不归入本节「换控件」。

5.3 扩展小结

先问：是换一种录入/展示组件，还是给现有组件加联动？前者 → 扩展控件；后者 → MapExt（见《表单三要素》业务逻辑章）。

六、四层如何拼成一张单

以「请假 + 行程 + 证明」为例：

元素	层	实现落点
请假类型、日期、天数、事由	主表数据	`Sys_MapAttr` on `ND1Rpt`
行程明细（多行）	从表 · 通用表格	`MapDtl` + `ListShowModel=0`
病假证明扫描件	表格附件或多图	`FrmAttachment` UploadType=Multi / ImgAth
本人手签	扩展 · 写字板	`UIContralType=HandWriting`
天数 = 到 − 从	（逻辑）	`Sys_MapExt` ExtModel=`ReqDays`

换检验检测、合同申报，只是从表改成二维矩阵、附件改成报告 PDF、扩展改成评分——四层骨架不变。

七、小结

主表数据：基础字段面板；UIContralType × MyDataType × LGType。
从表数据：MapDtl + ListShowModel（通用表 / 卡片 / 2 维 / 3 维 / 损益…）。
附件：字段附件（Single）vs 表格附件（Multi）vs 图片附件；文件在 FrmAttachmentDB。
字段扩展控件：高编号 UIContralType 专用组件；与 MapExt 逻辑扩展分工明确。
设计器换车间（经典/章节/VSTO），元素分类与 Sys_ 落点共用*。

附录：代码索引

主题	路径
控件枚举	`CCFlow/Components/BP.En30/En/EnumLab.cs` → `UIContralType`
附件上传类型	`CCFlow/Components/BP.En30/Sys/EnumAth.cs` → `AttachmentUploadType`
设计器面板	`Vue3/.../FoolFormDesigner/props/form/FormComponents.ts`
创建函数	`.../type-utils/CreateFieldFunctions.ts`、`CreateContainerFunctions.ts`
类型映射	`.../type-map/FormTypeMap.ts`
从表展示模式	`Vue3/.../MapDtl/ListShowModel/GPE_ListShowModel.ts`
附件实体	`CCFlow/.../Sys/FrmAttachment.cs`
字段渲染	`Vue3/src/WF/CCForm/OneMapAttr.vue`、`FrmEnd.ts`

表单元素的分类与实现：主表、从表、附件与扩展控件驰骋BPM驰骋低代码低代码工作流引擎