50 KiB
字段类型总表:44 类组件各管什么、值长什么样、哪一道闸判它
相关:option-source-design.md(选择类四兄弟的候选来源)、 form-data-integration-design.md(五种取数形态)、 ../README.md 的「表单设计」一节。 这一篇只回答三个问题:表单能摆哪些组件、每一格往
work.data里存什么形状、 配错了 / 填错了在哪一步被挡。
0. 一页看完
| 问题 | 结论 |
|---|---|
| 一共几类 | 44 类(utils/formLayout.ts 的 FIELD_TYPES,左侧字段库按 基础 / 选择类 / 人与附件 / 系统带出 / 布局 五段摆) |
| 这一轮新加的 | richtext 富文本、month 月份、year 年份、timerange 时间段、week 星期、location 定位、group 分组标题、spacer 空白占位 |
| 最新加的一类 | months 多选月份——一次圈几个月,连着几个月自动并成一段:挑 2026 年 10、11 两月,回填就是「2026年10-11月」。值仍是 YYYY-MM 数组,与 month 同一写法,见 §2.7 |
| 最近加的一类 | tabs 标签页——把这张单切成几页,其中一页可以整页让给一个外部系统,那个页面才占得满一屏。同样是版面不是值,但归属记在别的字段身上(每格一个 tab),见 form-tabs-embed-design.md §1 |
| 又加了一类 | embed 外部页面——把别的业务系统的页面嵌进表单,同一个功能不用在 OA 再开发一遍。它是版面不是值,但比 group 多一件事:它的 key 是环节字段权限的挂点,见 embed-page-field-design.md |
| 顺带捞回来的 | signature 手写签名——控件、只读态、导出、打印早就写好了,唯独左侧字段库没登记,于是界面上永远加不出这一类字段 |
| 老组件长了什么 | 文本那三类多了字数上限与校验正则;附件与图片多了允许类型 / 最多几个 / 单个多大;日期区间与时间段现在还会判起止先后 |
| 清单散在哪 | 前端 5 处、后端 4 处(见 §5)。以前分叉不会报错,只会在界面上悄悄少一格 |
| 谁来防 | frontend/src/utils/fieldCatalog.spec.ts:拿 Node 的 fs 直接读后端源码,把「前端有的后端也得有」钉成断言 |
| 权威判定在哪 | 只有后端一次(service/formruntime.py:validate_submit)。前端那几道(maxlength、accept、个数截断)只是别让人白等一次上传 |
1. 总表:44 类
「条件」那一列是流程设计器里能拿这一格比什么(口径 utils/fieldCapabilities.ts ↔
后端 service/threshold.py);「明细列」是这一类能不能当明细表的一列
(TABLE_COLUMN_TYPES,列与主表共用同一只录入控件)。
| type | 界面名 | 存进 data 的形状 |
明细列 | 条件 | 备注 |
|---|---|---|---|---|---|
text |
单行文本 | 字符串 | ✓ | 文本 | 可配字数上限、校验正则 |
title |
流程标题 | 字符串(= work.title) |
✗ | — | 一张表单只认第一个;口径见 service/titles.py |
textarea |
多行文本 | 字符串 | ✓ | 文本 | 可配字数上限、校验正则 |
richtext |
富文本 | Markdown 原文(字符串) | ✗ | 文本 | 排版只在显示那一步做,见 §2.1 |
number |
数字 | 数字 | ✓ | 数值 | 最小 / 最大 / 步长 / 小数位 / 单位 / 千分位 |
money |
金额 | 数字 | ✓ | 数值 | 可开中文大写;导出与标题跟着走 |
formula |
计算公式 | 数字或文本 | ✗ | 数值 | 每次提交后服务端重算 |
date |
日期 | 2026-01-31 |
✓ | 先后 | |
datetime |
日期时间 | 2026-01-31T09:00 |
✓ | 先后 | |
time |
时间 | 09:30 |
✓ | 先后 | |
daterange |
日期区间 | ["起","止"] |
✓ | 只判空 | 起止颠倒会被提交挡下 |
month |
月份 | 2026-03 |
✓ | 先后 | 月度报销 / 月度报表那一类 |
months |
多选月份 | ["2026-10","2026-11"](去重升序) |
✓ | 只判空 | 并成「2026年10-11月」;下拉 / 弹出框 / 平铺三档挑,见 §2.7 |
year |
年份 | 整数 2026 |
✓ | 数值 | 不是字符串,条件按数字比大小 |
timerange |
时间段 | ["09:00","10:30"] |
✓ | 只判空 | 考勤、会议、值班;同样判先后 |
week |
星期 | ["1","3","5"](1=周一) |
✓ | 只判空 | 排班、窗口开放日;条件按「包含」判某天 |
mobile / email / idcard / url |
手机号 / 邮箱 / 身份证号 / 网址 | 字符串 | ✓ | 文本 | |
address |
详细地址 | 字符串 | ✓ | 文本 | |
location |
定位 | {lng, lat, address}(物件) |
✓ | 只判空 | 见 §2.2 |
select |
下拉框 | 单个值或一串(勾了「可以选好几个」) | ✓ | 文本 | 候选来自手填 / 字典 |
picker |
下拉选择 | 同上 | ✓ | 文本 | 候选来自外部数据源 / 别的流程的单据 |
radio / checkbox |
单选 / 多选 | 单个值 / 一串 | ✓ | 文本 / 只判空 | |
switch |
开关 | 布尔 | ✓ | 是 / 否 | 控件摆出来就是关着的,必填那道闸认「关着=答了」 |
rate |
评分 | 整数星级 | ✓ | 数值 | max 是满星数 |
dept |
部门选择 | 部门路径串 | ✓ | 只判空 | |
cascader |
级联选择 | 从顶级到末级的字典项数组 | ✓ | 只判空 | |
user |
选人 | 登录账号数组 | ✓ | 只判空 | 只读态念成「姓名(账号)」,口径见 person-reference-design.md |
attachment / image |
附件 / 图片 | 附件对象数组 | ✓ | 只判空 | 可配允许类型 / 个数 / 单个大小,见 §2.3 |
signature |
手写签名 | PNG 的 data URL | ✓ | 只判空 | 导出只落「已签名」 |
relation |
关联审批单 | 对方单据的 job | ✓ | 只判空 | 认得它但不单列一格:它就是「下拉选择 + 来源=流程单据」 |
table |
明细表 | 行对象数组 | ✗ | 比列 | 列类型见 TABLE_COLUMN_TYPES;只读那一屏收不收折由 readonlyStyle 说(§2.9),一列能配的东西与主表字段同权、最多一行自动补(§2.10),列上也能挂外部取数、一行问一次(§2.12) |
auto |
系统带出 | 按带出的键 | ✗ | 文本 | 生成规则见 service/numbering.py |
group |
分组标题 | 无值 | ✗ | — | 见 §2.4 |
divider |
分割线 | 无值 | ✗ | — | |
description |
说明文字 | 无值 | ✗ | — | 阈值那句红字可以指定挂在这一格后面 |
spacer |
空白占位 | 无值 | ✗ | — | 只带一个 height(8-240px) |
embed |
外部页面 | 无值(连地址快照都不存) | ✗ | — | 版面,但不是 divider:要有标题、要认 key,见 §2.5 |
tabs |
标签页 | 无值 | ✗ | — | 版面。它只切页;归属记在别的字段身上(field.tab),见 §2.6。tabsMode 决定这几页怎么排:tabs 顶上翻页(存量表单都是这一档)/ collapse 摊在同一屏各自收折(新摆的默认);收折那档另有 tabsDefault 管进来先开先合,段上一个三态 collapsed 覆盖 |
hidden |
隐藏字段 | 按字段类型 | ✗ | 文本 | 默认整张流程不显示,值照常存 |
2. 这轮新加的东西里,四件需要说清的
2.1 富文本存的是 Markdown 原文,不是 HTML
第一反应是上所见即所得(contenteditable),但那等于把这格的值变成一段 markup:
导出表格、打印、条件判断、以及「这段到底填没填」全都要跟着解析一遍,
work.data 里还会混进别人贴进来的 style 与 script。
存原文就没有这些债:
- 录入控件是
components/oa/RichTextEditor.vue——左边 textarea,右边预览, 顶上那一排只是给不写语法的人省事的插入按钮,不是编辑器; - 上屏统一走
components/oa/MarkdownBlock.vue,底下是utils/preview.ts:renderMarkdown(marked 管语法、DOMPurify 洗脚本); - 导出 / 打印 / 标题里读的是
formruntime.markdown_text()那句去掉了记号的话, 单元格里躺的是「标题 / 加粗 一项」而不是## **标题**。
2.2 定位不接地图服务,这是有意的
本平台没配任何地图 key,硬塞一个第三方底图等于逼每个部署方先去申请一把。所以
location 存的是浏览器原生定位(WGS84)给的经纬度,加一句由人自己写的地址:
{lng, lat, address},accuracy / at 只是给填单人看这次取得准不准。
于是有一条刻意的活口:台式机、没授权、非 https 页面都取不到位置,那时只写一句
地址也算填了(locationFilled ↔ 后端 location_filled)。这一格存的是一整包,
条件分支只判得出「填了没有」,别拿它比大小。
2.3 附件那三个限制:前端挡体验,后端挡绕过
accept(预设:不限 / 图片 / 文档 / 压缩包 / 自己写)、maxFiles、maxSizeMb。
前端在选文件时就挡(AttachmentUploader.withinLimits:超小的整只丢掉、超个数的截尾),
后端提交时按每条附件自带的 name / extension / length 再判一次
(formruntime._file_problems)——绕过界面直接 POST 的人照样拦得住。
图片格没配 accept 时默认还是只收 image/*(acceptOf ↔ effective_accept)。
2.4 分组标题与空白格是版面,不是值
group 只把长表单切成几段给人看,spacer 只在格子里留一段空(默认 24px,8-240 之间)。
它们进 NON_INPUT_TYPES:不产生值、不参与必填、不进额度、不进回写映射,
「字段权限」那套开关对它们也就是灰着的。design.py 的 LAYOUT_ONLY_TYPES 会把
「给分割线勾必填」这种自杀式配置挡在保存那一刻。
标题同理分两半:spacer 的 label 上屏后一个字都不显示,所以它可以没有标题
(LABELLESS_TYPES ↔ formLayout.ts:LABELLESS_TYPES,两边一份口径);
group 的 label 就是那行抬头,缺了这一段就没名字,照旧要。
这条两边必须一致——前端放行、后端要标题,结果是设计器里加完空白格点保存才吃一句报错。
2.5 embed 是版面,但不能当装饰处理
embed(外部页面)跟 group 一样不产生值、不参与必填、挂不上阈值与额度,
所以它进同一族清单;两处不一样,都是故意的:
- 它要标题:那一行字是留痕和列表里唯一念得出它的东西,所以
LABELLESS_TYPES不收它; - 它认 key:
api/design.py校验字段时对divider直接continue,连字段名都不查—— 这一格必须走完校验,因为环节字段权限(formPerms)是按key生效的, 没有 key 就没法在某一环把它藏起来,而"某一环能不能看见这个外部页面"正是它最要紧的一道闸。
于是它有 key 却没有值:work.data 里不会出现这个键,提交校验、条件、额度、导出
都按"这一格不存在"走,唯一拿它做判断的地方是权限。设计见
embed-page-field-design.md。
2.6 标签页切的是「这一屏摆哪几格」,不是值
tabs(标签页)与 embed 同族:不产生值、不参与必填、挂不上阈值与额度、条件里也不出现。
两种排法用的是同一批分组、同一份归页、同一套环节权限,换的只是"一次只摆一页"还是
"摊在同一屏里各自收折"(判据见 form-tabs-embed-design.md §2.5)。
它和 group 那种分段标题的区别在归属:分段标题只是给人看的一行抬头,标签页真的决定
「这一格在不在这一屏」。归属记在格子身上(每个字段一个 tab,没写 = 第一页),
标签页自己不装子字段——因为「这一格能不能填」全系统都是按平铺的字段 key 判的。
三条口径值得单独记:
- 页签的 key 是标识,不是文案。设计器只让改名字;改 key 等于把那一页的格子悄悄送回第一页;
- 环节把这一格设成隐藏,藏的是整片(页签 + 每一页的格子)。只藏页签、留着第一页的格子, 会得到一张翻不完也填不完的表单;
- 某一页装的是外部系统页面时,那一页只装它,压在那一页上的格子不显示——所以保存那一刻 就挡(它们还参与必填与提交校验);
- 收折那一档"进来先开还是先合"配在容器上(
tabsDefault:全展开 / 全收起 / 只展开第一段), 段上那个三态collapsed只做个别覆盖。它和收折本身一样只是版面:合着的段照样参与必填、 联动、额度、导出,段头会写出"还差 N 项"。
设计与取舍见 form-tabs-embed-design.md。
2.7 多选月份并成一段,值的写法不变
months 那一格存的是 ["2026-10", "2026-11"]——与 month 同一句式(YYYY-MM),
去重、按时间排好,条件分支和导出读得懂,不像「2026年10、11月」那种人话还得再翻一遍。
给人看的那一句由 utils/formRuntime.ts:monthsText ↔ service/formruntime.py:months_text
现拼:连着几个月并成一段,同一年里只报一次年份,跨年那段两头都写全。
| 挑中 | 回填 / 只读 / 导出 |
|---|---|
| 2026-10、2026-11 | 2026年10-11月 |
| 2026-01、2026-02、2026-05、2027-07 | 2026年1-2月、5月、2027年7月 |
| 2026-12、2027-01、2027-02、2027-05 | 2026年12月-2027年2月、2027年5月 |
它装是一串月份,所以阈值与条件只判得出「填了没有」(fieldCapabilities.BAG_TYPES ↔
threshold.BAG_TYPES、routeExpression 的 OPAQUE_TYPES),额度也挂不上
(UNQUOTABLE_TYPES ↔ quota.UNCONTROLABLE_TYPES)——一串月份不是一笔能扣台账的数。
这一格长什么样由配的人挑:pickerStyle 三档,与设计器里「挑选方式」同一套取值
(utils/formRuntime.ts:monthsStyleOf ↔ service/formruntime.py:months_style_of)。
| 档位 | 界面上是什么 | 什么时候用 |
|---|---|---|
dropdown 下拉多选(默认,字段上不写东西) |
一只长得像输入框的按钮,框里挂「2026年10-11月」那一句;点开出那一年的 12 个月,挑完点外面就收 | 半行就放得下,一张单摆两三个月份格子也不挤 |
dialog 弹出框多选 |
同一面盘搬到屏幕正中的弹出框里,格子大一号;改的是草稿,点「确定」才写进这一格,取消等于没挑 | 手机上、或那一屏本来就窄 |
inline 平铺点选 |
12 个月一直摊在这一格里,不用点开 | 想让「这个季度选了哪几个月」一眼看全;代价是吃掉一整行,属性面板会顺手把这一格铺满 |
这一类没有「自动」那一档(只有一档默认,摆两档等于让人猜),所以 carriesStyleChoice
把它算进"要摆挑选方式那一栏",carriesOptionSource 仍然不算它——那一句只管候选来源那四类。
明细表那一列同理,列上也能挑;明细格子里永远不给摊开(一行的高度放不下一个盘子)。
2.8 明细表那一列锁得上:column.readonly
用户那句原话是「表单的明细表中的字段,无法设置不可编辑」。查下来缺的不是运行时的判据,
而是设计器里的入口:列上那份 column.readonly 一直有人认(填单那一屏把它递给录入控件),
可界面上唯一能改它的地方是「自动带出」底下那颗**「带出后允许填写人修改」**——没配带出的列
压根锁不上,配过的列也只能反着说(勾上=不锁)。
现在明细列卡的第一行跟主表一样摆了「只读」,与必填并排(标题 / 类型 / 标识 / 必填 / 只读 / 删除
钉死在第一行)。三处读写的是同一份 column.readonly,不另发明第二个标记:
| 谁 | 认这一份的哪一句 |
|---|---|
| 填单那一屏(桌面与手机同一只组件) | FormRenderer 把 column.readonly 递给 FormFieldControl,锁着的格子出只读态那一支;表头挂一枚锁(为什么点不动)+ 那一列铺一层底色(哪几格点得动) |
| 设计器 | FieldInspector 列卡上那颗「只读」+「自动带出」底下那颗「允许填写人修改」(反着说,仍写同一格);写了本行公式那一列的锁勾死解不开(公式列没有录入框)——§2.11 之后有出口:勾了「公式带入后允许修改」的那一列有框,锁也解得开 |
| 提交那道闸 | formruntime._row_problems:锁着的列不卡必填,那一格里已经躺着的值照旧过格式那几关 |
锁上之后必填要让路,理由是同一句老话:必填卡的是人,而锁着的列根本没有录入框——那一格的值
归默认值 / 自动带出 / 关联带出 / 额度台账给,人改不动却永远被催「还没填写」,这张单就地卡在这一环,
跟「屏幕上没有那一格,却说请先填写它」是一种坏法。所以锁着的列不摆红星、属性面板里必填那颗灰掉
(勾还留着,解开锁就回来)。三条分寸:只让「必填」这一条;只认 readonly 这一个标记(写了本行公式
那一列没勾只读,公式算不出值仍是配置坏了,照旧拦);整张明细表那一层的环节权限一个字没动——
环节把整张表设成只读走的还是 effective_perm(FormRenderer.isLocked),列上这一层只在表本来摊开
给人填时说话。
锁着的列管的是"人改不改得动",不管"这批值收不收":提交时按环节权限过滤写入的是
formruntime.editable_keys,粒度是整张表(那一列的值由开放接口或脚本直接写进来,不会被这一层挡)。
设计器在锁着又没配任何值的来路时会当场说一句(columnLockedWithoutSource:默认值 / 自动带出 /
本行公式 / 关联带出的目标列 / 额度逐行控写的那几列都算来路),因为那一列从此谁也填不进东西。
钉在 FieldInspector.column-readonly.spec.ts、FormRenderer.tableCellReadonly.spec.ts 与
scripts/check_table_column_readonly.py。
2.9 明细表提交之后可以先收着:readonlyStyle
用户那句原话是「表单中的明细表在填写的时候是展开状态,流程提交后我希望明细表都是收折的状态, 给我一个地方可以配置」。缺的不是渲染能力(只读那一支本来就会把整张表画出来),而是没有那个地方: 一张报销单摆两三张明细表,审批人进来先翻三屏表格才找到自己的签名框,而设计者对此一个字都说不上。
配置落在明细表那一格身上(field.readonlyStyle),入口是属性面板明细表那一支的「流程提交后的展现」:
| 档 | 只读那一屏(提交后 / 审批环节看单 / 已办 / 单据详情) | 填单那一屏 |
|---|---|---|
留空 / expanded |
整张摊开,连段头都不多摆一行——存量表单的画法一个字不变 | 摊开 |
collapsed |
先给一行段头「共 N 行 · 合计 X」,点它才摊开,再点收回 | 摊开 |
四条分寸是刻意的:
- 只管读。填单那一屏永远摊开:收着的表里没有录入框,人没法往里敲字,
把这一档做成"什么时候都收"就等于把明细表变成一个不能填的东西。判据
utils/formRuntime.ts:tableReadonlyCollapsed只在FormRenderer只读那一支被问一次。 - 打印那一份永远摊开。纸上没有"点一下摊开"这回事,收着的那些行等于根本没印出来,
而缺的那一半在纸面上看不出缺——这一条比"看着清爽"重要。判据复用现成的
flattenTabs(打印页是唯一传它的地方),不另发明第二个"这是打印"开关。 - 人手动点开那一份不写回表单。段头上的开合记在组件里(字段名 -> 这一刻摊开与否), 换一张单、刷一次页面就回到配置说的那一档:审批人点开看一眼是他这一趟的事, 不该顺手把全公司以后看单的样子改掉,更不该因为谁点一下就把表单定义弄脏。
- 只认一处渲染。全项目只读明细表的画法只有
FormRenderer那一份(桌面、审批详情、 单据详情、介入面板、试跑弹窗共用),所以这一档配一次就在所有只读屏生效; 明细列 / 行数 / 环节权限那三套口径一个字没动。
手机端不吃它:那边早有自己那一档——MobileFieldStyle 的 card(收成一行,点开逐条)
与 list(在节里逐条摊到底),且明细格默认就是 card。两份开关各说一件事(手机看的是配好的版式,
电脑看的是这张表在只读屏的默认开合),不互相覆盖,免得同一件事两处各说一遍。
钉在 FormRenderer.tableReadonlyStyle.spec.ts(四屏各是什么样)与
FieldInspector.tableReadonlyStyle.spec.ts(只有明细表摆这一栏、挑回默认那档就把键摘掉、
换类型收掉残骸)。这一档是纯展现,后端不读它,clean_formats / clean_option_source
也都不收它(不在 FORMAT_KEYS / LIMIT_KEYS 清单里),存下去就是字段上一个键。
2.10 明细列与主表字段同权,最多一行的表先把那一行摆好
用户那两句是「明细表里面的列,我希望也可以和主表字段一样可以进行各种配置」与「明细表最多只有 一行的时候,我希望可以自动帮我带出一行」。
先说结论:一列就是一个字段。查下来缺的不是运行时的判据——FormRenderer 把列上那份对象原样
递给 FormFieldControl,所以列本来就认得 placeholder / maxLength / pattern / min / max /
accept / cascadeFrom 这些键,只是设计器里没地方写。于是这一轮没有另发明一套"列配置"的
schema:配置全写在列上那一份对象上、与主表同一个键名,补的是入口和那两道闸。
| 一列能配的 | 写在哪 | 谁读它 |
|---|---|---|
| 占位提示 | column.placeholder |
同一只录入控件(列与主表共用的那只),填进去就是原生 placeholder |
| 列说明 | column.help |
表头列名后那一枚提示(table-column-help),指针停在列名上就出,不占格子高度 |
| 字数上限 / 校验正则 | column.maxLength / column.pattern |
界面上 maxlength 挡体验,提交那道闸判(value_problems,正则仍整格匹配) |
| 取值上下限 | column.min / column.max |
<input type="number"> 只标红不拦人,提交时 _range_problem 按同一份上下限再判一次 |
| 步长 | column.step |
只摆给数字列:原生数字框的箭头与滚轮每次调多少,留空 = 浏览器那个 any(金额那只框自己钉了 0.01,没这一栏) |
| 附件三个限制 | column.accept / maxFiles / maxSizeMb |
上传前 AttachmentUploader 挡,提交时 _file_problems 判 |
| 级联自 | column.cascadeFrom |
本表另一列选了什么,这一列的字典项只留它下面那几项 |
| 隐藏此列 | column.hidden |
visibleTableColumns:填单与看单两支都连表头都不摆(第三段单说) |
| 列宽 / 对齐 / 合计 | column.width / align / aggregate |
表格自己那三样,第二段单说 |
| 外部取数(逐行) | column.fetch |
与主表那一格同一套配置与执行器,按行各跑一次,见 §2.12 |
入口收在「更多配置」里,但收了也念得出。 列卡第一行仍是钉死的那几样(标题 / 类型 / 标识 /
必填 / 只读 / 删除),外加新摆的上移 / 下移 / 复制——以前调一次列序等于删了重加。其余那一长串
收进一个折叠栏(column-more-toggle),规矩跟侧栏 SidePanel 一样:门关着时,入口那一行就是
唯一的可见状态,所以配过几样写在角标上(「已配 2 项」),且只数这一列类型用得上的那些(步长只数数字列
那一格,金额那只框压根没这一栏)——换类型
该收掉的残骸不占位置,否则人以为配过什么,其实那一栏压根没摆出来。用不上的格子干脆不摆:归本行
公式算的那一列没有录入框,占位提示与上下限轮不到它;文本列的合计只有「不合计」与「计数」两档。
换列类型时带走不走的旧配置一并清掉(changeColumnType 收展现格式、字数与正则、附件限制、级联、
合计那几群),与主表 changeType 同一份清单,后端 clean_formats 对明细列做的是同一件事——
留下的老写法会藏在新控件底下继续生效。
表格自己那三样是纯展现,不进提交那道闸。
- 列宽
width:这一列的最小宽度(自动 + 96/120/160/200/260/320/400 七档),表头那行字 放不下时还会再宽一点,整张表超出容器仍走横向滚动。判据columnMinWidth;没配过的列照类型自动 分配,存量表单一个字节都不动。 - 对齐
align:auto(不写类,跟着表格默认靠左)/ 靠左 / 居中 / 靠右。判据columnAlignClass。 - 合计
aggregate:求和 / 平均 / 最大 / 最小 / 计数,选中的列在表尾多摆一行念这个数 (TableAggregateRow.vue)。非数与空格子不进统计,小数位跟着那一列自己的precision写; 计数那一档任何列都能配,其余四档只认number/money——给文本列配求和会算出一堆 0, 所以界面上压根不摆那几档,后端也拦。段头(§2.9 收折那一行)上原本的「合计 X」现在优先听 点名:哪一列显式配了sum就念哪一列,没配才回落到「第一个数字列」,且标签与数字问同一列—— 以前不点名,段头写着「运费」、念的却是「金额」那一列的数。
这三样后端只在设计期判配置本身认不认识(列宽在 60-640px 之间或留自动、对齐与合计是合法值、
那四档没配在非数字列上、min 不大于 max),一个字不进 validate_submit:它们不改任何一格的值。
hidden 这一样只管屏幕上摆不摆,得说清。 藏起来的列连表头都不出现,但值照常保存、照常导出、
照常参与本行公式与关联带出,也不卡必填——column_not_for_people(勾了只读、整列藏起来,两样
都是"人改不动这一格",而必填卡的是人,与 §2.8 同一把尺子)。红星不摆、表头宽度也不给那颗星留位,
属性面板里必填那颗灰掉(勾还留着,取消隐藏就回来)。设计器在藏着又没配任何值的来路时会说一句
(默认值 / 自动带出 / 本行公式 / 关联带出 / 额度逐行控写都算来路):那一列从此谁也填不进东西。
这一样是给机器留的——项目编码、物料 ID 那类"带出来给公式和回写用、人不需要看"的列。
手机端那一份读单(components/oa/mobile/useFormPlan.ts)跟着同一份口径:藏着的列不进逐条那几行,
摘要那一行「合计 X」也优先念列上点了求和的那一列——同一张单子在电脑上念一个数、在手机上念另一个数,
比两边各念各的更让人不敢信。钉在 useFormPlan.spec.ts。
最多一行的表自动带出那一行。 maxRows === 1 的明细表压根没有"再加一行"这回事(右上角那颗
+ 一到一行就灰了),可格子还是得点一下 + 才出现——一张空表看着就像不能填。现在进这一屏就补
一行,补的这一步与点 + 走同一条路:同一份 emptyRow、同一份 rowSeed、同一遍
applyRowFormulas,所以默认值、自动带出、本行公式都按老口径落,不多算一次也不少算一次。三条边界
是刻意的:只在填单那一屏补(只读态与打印不许给单据添行);环节把这张表设成只读、或整格藏起来
时不补(那一屏根本没有录入框,补出来的行只是把 data 弄脏);落库前 normalise_rows 照旧把一格
没填的空行剔掉,所以补出来的那行没人碰,也不会多存一条空记录。设计器在「最多行数」那一栏下说破
这件事(table-single-row-hint),别的行数不啰嗦。
钉在 FieldInspector.columnMore.spec.ts(角标数几样、每一样写进列上哪个键、用不上的格子不摆、
换类型收残骸、列序与复制)、FormRenderer.tableColumnDisplay.spec.ts(藏着的那一列数不出来、
列宽与对齐落到 <th>/<td> 上、表尾念的数、最多一行自动补)、formRuntime.tableColumnConfig.spec.ts
(判据本身)与 scripts/check_table_column_config.py(21 句:藏着的列不卡必填、上下限提交时判、
格式那几问不再跟着必填走、列宽对齐合计只在设计期判)。
2.11 公式带进来的那个数可以让人改:column.formulaEditable
用户那句原话是「表单中明细表中引用公式带入的值,为什么不能编辑?我需要可编辑」。查下来这不是 坏掉,是一直以来的有意画法:列上一写公式,那一格同时失去两样东西。
- 屏幕上没有录入框——
FormRenderer认column.formula那一支,摆的是一句现算的文本 (cellFormulaText),判据是columnHasNoInput(§2.8、§2.10 那把尺子加一句"归公式算")。 - 数据上守不住——
applyRowFormulas每轮改动都把这一列整列重算,主表那一格一动,rowFormulaSignal那道 watch 还会再重算一遍。就算界面上硬塞一个框,敲进去的数也会在 下一轮重算里被盖回公式那个。
只补第 1 件的功能是假的(改得动、留不住,比不让改更气人)。所以这一档两件事一起管,落在列上
一个新键 formulaEditable:没写 = 老画法,几百张存量表单的明细表一个字不变。
| 谁 | 认这一档的哪一句 |
|---|---|
| 填单那一屏(桌面与手机同一只组件) | columnFormulaEditable 为真 → 那一格出 FormFieldControl,公式先把数摆在框里;表头从一枚锁换成一枚 fx |
| 重算 | applyRowFormulas 跳过"这一列点了这一档 且 行上躺着凭据"的那一格,其余照旧整列重算 |
| 设计器 | 列卡「本行公式」底下那颗「公式带入后允许修改」;公式一清空这一档跟着撤掉;这一档生效后那枚「只读」锁也解得开了 |
| 提交那道闸 | 一个字没动:那一格现在有框了,必填照卡、值照过格式那几关;公式列的默认值照旧不复活 |
凭据落在行上:row._manual = ['payAmount'](列标识的数组),与关联带出那一份 _link 同一层,
下划线开头 = 导出、打印、明细导出都看不见它。它必须一路不丢才算数:编辑中的整型
(trimRows / normaliseRows)与落库前的整型(后端 formruntime.normalise_rows)都把它跟
_link 一起留着,否则下一环的人重新打开这张单,昨天改的数就悄悄变回公式算的那个。
三条分寸是刻意的:
- 只豁免改过的那一格,不豁免整列。没动过的格子照旧跟着公式走,主表那个运费一涨, 没人碰过的那几行该变的还是变。
- 清空那一格 = 交回公式,行上那颗「恢复公式值」(
formula-reset-*)点一下走的是同一条路: 撤凭据 + 重算。手工覆盖一旦没有退路,比不让改更难用。 - 锁与隐藏压过这一档。
columnNotForPeople(勾了只读、整列藏起来)在前,formulaEditable在后,判据只columnFormulaEditable这一处,填单与设计器读同一把尺子;属性面板里那一档 在已勾只读时灰着点不动,并说一句为什么。
这一列的数仍然只有前端会算(compute_formulas 只管主表 type=formula 那一格),所以走接口
直接提交的单子得自己把这一列算好——这一点与公式列一直以来的规矩相同,tableColumnFormulaHint
里那句"由前端算"没说两遍。钉在 formRuntime.formulaEditable.spec.ts(判据本身、凭据一路不丢)、
FormRenderer.formulaEditable.spec.ts(那一格真是录入框、改过的那一格不被盖回、清空与恢复都交回公式、
没点这一档仍是文本)、FieldInspector.columnFormulaEditable.spec.ts(这一档只写一个键、公式
清空就撤、锁解得开)与 PYTHONPATH=. python3 scripts/check_table_formula_editable.py(12 句:
凭据不丢、这一档不锁列也不放宽校验、默认值没复活、设计期不报错)。
2.12 明细列也能逐行取数:column.fetch
用户那句是「明细表中的字段是否可以配置取数,取我配置的外部数据源」。真实场景:收款明细每
一行填了收款人,开户行与银行帐号要按这一行那个人去 ERP 查。以前只有主表字段挂得上
fetch(fetch_fields 见着 type == "table" 就跳过),列上那一格只能人填或走关联带出。
没有新键:列上写的那份 fetch 与主表字段是同一个形状、同一个执行器(binding.entries
那一套多源 / merge / args / picks / onError / revalidateAfter / freezeAfterStart),
只是逐行各跑一次,值写进这一行的这一列。挂不得上走的是同一句 canCarry(type,'fetch')
——装得下一个数或一句话的那些列能挂(文本、多行、数字、金额、日期时间、月份、年份、手机、
邮箱、身份证、网址、下拉、单选、评分),多选 / 部门 / 附件 / 日期区间 / 开关那几类主表本来就
挂不上,列上同样挂不上。归本行公式那一列没有录入框,配了也没人看得见。
| 谁 | 认这一档的哪一句 |
|---|---|
| 设计器 | 列卡「更多配置」底下那块「外部取数」,用的就是主表那只 FetchPanel。「带出去向」的下拉只有这张表的其它列;配完之后角标上「已配 N 项」把它算一样(columnExtraConfigs 数了 fetch);这一列勾了「只读」而没配来源那句黄字提醒,在配了取数之后自动收声——那一格的答案是查出来的,本来就该锁着 |
| 入参读哪一格 | 作用域 = 整张单 + 这一行,与主表字段同名的列以本行为准,{form.x} 既能读主表也能读本行的列。跟本行公式(applyRowFormulas)吃的是同一份作用域,配的人不用记第二套写法 |
| 带出去向落哪 | 只落这张明细表的其它列。写主表那一格等于让最后一行去盖表头:三行的表盖三次,谁赢看运气 |
| 填单那一屏 | FormRenderer.runRowFetches 按行各取一次给人看,一张表攒完补丁再一次性写回(逐行各写一次会把前面几行刚取回的那份按旧快照盖掉)。「多久算旧」到点重取按行各算一份——入参指纹的键是 表名#行号#列名;freezeAfterStart 那一档逐行一起冻结 |
| 提交那道闸 | 后端 fetch.apply_form → _apply_rows 按同一份配置逐行再取一次并覆盖,前端塞不进假值;跑的是 data 里当前那几行——删掉的行不再取一次,新加的那行当场补得上 |
| 取不到数怎么报 | 「明细表「收款明细」第 2 行的「银行帐号」的外部数据取不到:ERP 连接超时」。整张表在这一环被藏起来时 onError=block 降级成不挡(环节权限挂的是表不是列),取数照发、留痕照记 |
| 留痕 | data["_fetch"]["收款明细.bankAccount"],底下 rows: [{row:1,…},{row:2,…}]。键必须是「表名.列名」——两张表可能有同名列,同一列每一行都得留得开 |
| 删列 | 删掉一列时指向它的 picks 一起清(utils/formPrune 按这张表剩下的列名滤,那句「掉在地上的指向」挂在 列名.带出键名 上);运行时也只往还在的列写,与主表那几处共用同一把闸(binding.live_target) |
三条分寸是刻意的:
- 行的增减还是人说了算。这一档是"已有的 N 行各自去问一次",不是"一条查询生出 N 行"—— 后者(结果集控件)仍然没做,边界见 sql-autofill-design.md §6 第 4 条。
- 一行一调。十行十次外呼,再叠
revalidateAfter是十次乘以刷新次数,数据源上的缓存 TTL 与rate_limit_qpm要先抬到量级上。 - 权威在服务端,与主表那一格同一条红线:外部回来的值只提供一个值,不决定流转。
方案与更细的口径在 form-data-integration-design.md §9.2。
钉在 PYTHONPATH=. python3 scripts/check_row_fetch.py(34 句:逐行取数与覆盖、入参作用域、
带出去向只认本表、点行号的报错、整表隐藏时降级、留痕摊得开行号、设计期那几道闸门)与前端
formFetch.rowFetch.spec.ts、FormRenderer.rowFetch.spec.ts、
FieldInspector.columnFetch.spec.ts、formPrune.spec.ts。
2.13 选择类字段能挂好几套候选来源:optionRoutes
用户那句是「我一个组件中为什么不能配置多个外部数据源、数据字典等等,我通过表单中字段来判断
我该组件中该用什么数据源」。以前 optionSource 是一维一答,换一家只有摆三格 + 显示条件
(三个字段名 = 三份导出列 + 三套环节权限)或者去对面求一个聚合接口。
没有新字段类型、没有新接口:字段上多挂一份有序清单 field.optionRoutes(最多 8 条),
每一条 = 一个触发条件(when,与 visibleWhen 同一份结构化条件)+ 一套候选来源配置
(dict / dataSource / process / manual 各带自己那几格)。自上而下第一条成立的用它,
一条都不成立回落到字段自己那一份——老表单没挂清单,走的正是这条路,一个字节不用改。
同一寸在「取一个值」那一头也有:fetch.sources[].when(单源老写法也能挂)。
| 谁 | 认这一档的哪一句 |
|---|---|
| 设计器 | 多选那几格「同一个字段的几家」(各挂一条「某字段 = 某一个值」)时,属性栏给一颗「并成一格」:条件搬进清单、来源各归各条、指着旧名字的带出跟着搬(utils/formMerge.ts,判据不新增)。单格配置在属性侧栏「候选来源」下面那一栏「同一格换一家候选」(design/OptionRoutesEditor.vue):挑一格点「一家一档」,它有几个取值就铺几条卡片、条件替写好;外部那几家在第一家的卡片里配好带出后点「套给其余几家」;字典那一条上那颗按钮直接把人送到「字典带出」那块。「外部取数」面板里每条源还多一颗「什么时候调这一条」 |
| 渲染与取候选 | 先摊成一张视图再喂给既有函数:前端 optionSource.optionFieldView → formLinkage.effectiveOptions,后端 dicts.option_view → dicts.effective_options。视图只换来源那一维,pickerStyle / multiple / linkFill 原样留着 |
| 判越界 | 跟着命中那一条走:constrainsValues(field, data) ↔ dicts.constrains_values(field, data)。这一分钟是字典(要把关)、下一分钟可能是外部数据源(不把关) |
| 字典带出、翻名字、级联筛候选 | 全部读视图,所以取的是命中那一本的附加值与那一条自己的「显示 / 存值」;命中那一条不是字典时字典带出一个字都不写 |
| 预取与删前检查 | 路由里那几本字典一起进预取清单(codes_of),也算「哪些表单在用」(dicts.used_by_forms / fetch.used_by_forms);漏一处就是删掉一把只挂在路由里的字典、那一格当场空 |
| 上游 | 路由的 when 与那一条的 cascadeFrom 并进 conditionDependencies / condition_dependencies,那一格一改就重算候选与失效值 |
| 保存那一刻 | api/design.py:clean_option_source → dicts.clean_routes:每条只留属于它那一种来源的那几格、全勾状态不留、第 9 条起截掉、一条不剩把键抹掉;主表字段与明细列同一句。挂了这份清单也算「这一格有候选来源」——那道「选项类字段未配置任何选项」不再拦它(form_problems ↔ validateFields 两边同一口径),因为「先选分类再问那一家」的那一格常常故意把自己那一份留空 |
| 脏条目 | 当没配:认不出的来源、空条目一律丢掉,宁可回落,也不留一只永远为空的挑选器 |
那一条候选还能自带一份带出(optionRoutes[].fill,只给外部数据源那一条):「换一家」
从来不只是换一份候选清单,而是换一整套答案——挑的是 ERP 那家供应商,开户行与信用额度就得回 ERP 查。
以前要配出这个结果得把同一条判据抄两遍(候选那一格写「差旅问 ERP」,取数条目再写一遍),漂开的
症状最难查:候选换了家、带出还是上一家的。现在那一条自带「问哪一家 / 带什么入参 / 哪几个键写进
哪几格」,后两样留空就跟着这一条走;运行时摊成一条普通的取数条目丢给同一个执行器(同一个入参写法、
同一份留痕、同一档 onError),只多一个 fillOnly 记号——只写「带出去向」那几格,绝不盖这一格
刚被人在候选里挑中的那一个值;一条都不成立或命中的那条没自带,照旧读字段上那份 fetch。
字典那一家走 autoFill、流程单据那一家走 linkFill,那两条本来就跟着各自命中的对象走,
不再各挂一层。所以「一家外部数据源 + 一家数据字典」这一对最常见的配法是各写各的:外部那一条在卡片里
配「这一家的带出」,字典那一条在「联动」面板的「字典带出」里配。带出读的是命中那一本字典的附加值
(applyAutoFill ↔ apply_auto_fill 都先摊视图),命中那一条不是字典时一个字都不带;字段自己没挂
字典、路由里挂着字典时 autoFill 不再被当上一家的残骸洗掉,两处都没字典才洗掉并说一句「这一档不起
作用」;那一栏现在对「只有路由挂字典」的格子也出现,能带哪些列是那几本附加值列的并集。见
option-source-routing-design.md §5.1。
界面上是那张卡片下面多出一栏「这一家的带出」,设计期门牌写「第 N 条候选来源的带出」。
顺带两档都在这轮补上(同一批反馈):field.allowOutsideValue(带回来的值不在候选里也收下,
默认关;勾上之后页面不清值、提交不判越界、界面上补一行候选);回看那一屏改为按
存过的那份值评条件、因显示条件不成立被收走的必填格不再卡提交。
方案、为什么以前只能一个、以及保留的那一寸,见
option-source-routing-design.md;钉在
PYTHONPATH=. python3 scripts/check_option_routes.py(不碰库)、
PYTHONPATH=. python3 scripts/check_option_route_fill.py(那一家的带出)与前端
optionSource.routes.spec.ts、formFetch.when.spec.ts、FormRenderer.optionRoutes.spec.ts、
design/OptionRoutesEditor.spec.ts、design/FetchPanel.when.spec.ts、optionSource.fill.spec.ts、
formFetch.routeFill.spec.ts、design/OptionRoutesEditor.fill.spec.ts(带出那一栏的接线),
改名与删格子时跟着搬的落点在 formRename.spec.ts、formPrune.spec.ts。
3. 配错了在哪一步说
| 时机 | 判什么 | 在哪 |
|---|---|---|
| 设计器保存 | 类型不认识、纯排版勾了必填、该不该有标题、正则编译不过、字数上限离谱、附件三个限制越界、空白高度出格、明细列类型不支持、外部页面没挑页面 / 页面被删 / 参数是那个页面用不上的、标签页没配页 / 页签没名字 / 页签标识重复 / 外部页面那一页上还压着格子 / 摆了不止一个标签页、明细列那几样新的:列宽不在 60-640px 也不是「自动」、对齐与合计的写法不认识、非数字列配了求和(§2.10)、上下限写反;列上那份 fetch 与主表同一套闸门(§2.12):源不存在 / 已停用、入参引用了不存在的格子、带出去向落到主表字段或落到自己 |
前端 utils/formLayout.ts:validateFields(明细列那一串走 utils/formRuntime.ts:validateTableField)与 utils/formRuntime.ts:embedConfigProblems;后端 formruntime.validate_schema(含 embed.problems 与 column_display_problems)+ api/design.py 的字段校验 |
| 保存落库前 | 换了类型就收掉上一类留下的配置:展现格式按 FORMAT_OWNERS,限制按 LIMIT_OWNERS |
api/design.py:clean_formats |
| 填单时 | maxlength、accept、个数与大小、年份与月份的原生控件 |
FormFieldControl 与 AttachmentUploader(只为体验,不是闸门) |
| 提交时 | 必填、正则(整格匹配)、长度、月份/年份写法、多选月份那串里每一项的写法、星期取值、时间段与日期区间的先后、附件类型/个数/大小、数字与金额的取值上下限(界面上只标红,拦不住人)。列上配了逐行取数的,这一趟先按同一份配置逐行重取再判(§2.12)。明细行里锁着(readonly)或藏着(hidden)那一列不卡必填(§2.8、§2.10),已躺着的值照判;而且格式那几问不再跟着必填走——以前整段套在「没勾必填就跳过」里,于是非必填的列填什么都没人看,那三道限制等于只在浏览器里说了算 |
后端 formruntime.validate_submit(主表 value_problems,明细行 _row_problems,两者同一份判据) |
| 只读 / 打印 / 导出 | 每一类念成一句人话 | FormFieldControl 只读那一支、api/export.py:cell_text、service/titles.py:_field_text。embed 无值,导出与打印里天然什么都不落——那条地址上挂着一次性免登短码,落进导出件等于把钥匙抄进表格 |
正则按 fullmatch 判:半匹配会让 \d{6} 放过 abc123456def,配的人以为挡住了、其实没挡。
这句也写在属性面板那栏的提示里。
4. 加一类字段要动哪几处
frontend/src/types/index.ts:FieldType加一类,值装得下单个值就顺手加进TABLE_COLUMN_TYPES;frontend/src/utils/formLayout.ts:FIELD_TYPES排进左侧那一列该在的位置;components/oa/design/FieldLibrary.vue的META:没登记 typecheck 直接红 (Record<FieldType, ChipMeta | null>,不想单列就写null,别删——手写签名就是被"删"过一次);components/oa/FormFieldControl.vue:编辑态控件 + 只读态怎么念;utils/formRuntime.ts↔backend/app/service/formruntime.py:值形状、必填判定、提交校验;utils/fieldCapabilities.ts↔backend/app/service/threshold.py/quota.py:归组,决定能不能挂阈值与额度;utils/routeExpression.ts:条件搭建器该给什么控件;backend/app/api/design.py:FIELD_TYPES、LAYOUT_ONLY_TYPES、LIMIT_OWNERS;api/export.py与service/titles.py:落地成什么文本;i18n/locales/zh.ts与en.ts:fieldTypeXxx加两段说明——少一份翻译不会报错, 只会在英文界面上印出裸的 key,i18n/localeParity.spec.ts替两边数一遍;- 跑
pnpm vitest run——utils/fieldCatalog.spec.ts会替前后端两边数一遍。
5. 唯一口径在哪
| 说什么 | 前端 | 后端 |
|---|---|---|
| 有哪些类型、左侧怎么摆 | utils/formLayout.ts:FIELD_TYPES + design/FieldLibrary.vue:META |
api/design.py:FIELD_TYPES |
| 值形状与必填 | utils/formRuntime.ts |
service/formruntime.py |
| 能挂什么面板、能比什么 | utils/fieldCapabilities.ts |
service/threshold.py + service/quota.py |
| 明细列能用哪些类型 | types/index.ts:TABLE_COLUMN_TYPES |
service/formruntime.py:TABLE_COLUMN_TYPES |
| 明细列锁不锁(只读) | 一份 column.readonly:FieldInspector 那两处的开关 + FormRenderer 递给录入控件 |
service/formruntime.py:_row_problems(锁着的列不卡必填) |
| 明细列能配什么(与主表同权) | 一份 column.*:design/FieldInspector.vue 列卡那一栏「更多配置」+ utils/formRuntime.ts(visibleTableColumns / columnNotForPeople / columnHasNoInput) |
service/formruntime.py:_row_problems(藏着与锁着都不卡必填、格式照判)+ column_not_for_people |
| 明细列在表格上怎么摆(列宽 / 对齐 / 合计) | types/index.ts:TABLE_COLUMN_WIDTHS / TABLE_COLUMN_ALIGNMENTS / TABLE_COLUMN_AGGREGATES + utils/formRuntime.ts:columnMinWidth / columnAlignClass / columnAggregate |
service/formruntime.py:COLUMN_WIDTH_MIN~MAX / COLUMN_ALIGNMENTS / COLUMN_AGGREGATES(column_display_problems 只在设计期判) |
| 最多一行的表自动补那一行 | FormRenderer.vue:singleRowTables(与点「+」同一份 emptyRow + rowSeed + applyRowFormulas;只读、锁着、整格藏起来的表不补) |
—(normalise_rows 照旧剔空行,后端不必知道这件事) |
| 明细表只读那一屏收不收折 | 一份 field.readonlyStyle:FieldInspector 那一栏 + utils/formRuntime.ts:tableReadonlyCollapsed(只读那一支问一次,打印走 flattenTabs 强制摊开) |
—(纯展现,后端不读,两个 clean 都不收这一键) |
| 条件里的控件与比较符 | utils/routeExpression.ts |
engine/conditions.py |
| 空白格之外谁必须有标题 | utils/formLayout.ts:LABELLESS_TYPES |
api/design.py:LABELLESS_TYPES |
| 有哪几页、谁在哪一页 | utils/tabPages.ts(含伪装给 iframe 那一格的 key 口径) |
service/tabpages.py(同一份措辞与页数上下限) |
| 谁把它们钉在一起 | utils/fieldCatalog.spec.ts(读后端源码比清单)+ i18n/localeParity.spec.ts(比中英词条) |
— |