unis-oa/docs/field-self-visibility-desig...

12 KiB
Raw Permalink Blame History

显示条件判自己那一格:字段的显隐由它自己的取值决定

相关:form-field-catalog.md(每一类字段有什么值、能不能判)、 option-source-design.md(候选与选项级 when)、 mobile-form-layout-config.md §4.2(手机上那两屏同一句判据)、 option-source-routing-design.md §6(同一批反馈里的另一头: 回看那一屏按存过的那份值评条件,以及因显示条件被收走的必填格不再卡提交)。 这一篇只讲一件事:联动条件(显示 / 必填 / 只读)里可以点名的那一格,就是配条件的那一格自己。

0. 一页看完

问题 结论
需求 「表单中字段的显示判断条件,需要可以设置判断本身字段的值情况来确定是否可以展示」
以前 设计器把本字段从条件清单里筛掉(LinkagePanel.conditionSources 那句 key !== field.key),后端保存报「联动条件引用了自己」。想配只能造一个中间变量绕一圈
现在 三栏条件(visibleWhen / requiredWhen / readonlyWhen)里都能挑「本字段」;选项级 when 同理
落库 一个字都没变:还是 {match, rules},只是允许 rules[].field(或 rules[].valueField)等于本字段的 key,不加新键、不做数据迁移
判法 走原来那条 compare:读的就是这一格此刻的值,没有第二套引擎
一键配法 侧栏「满足条件才显示」下面两颗开关:「本字段有值才显示」= {field: 自己, op: notEmpty},「本字段没值才显示」= empty;选中态再点一下撤掉。已经配了别的显示条件时这两颗不摆(它们写的是整条条件,摆着点一下就把人配好的那一串换掉了),改条件走弹窗
什么时候真正合身 值由系统写进来的那一类格子:外部取数(fetch)、字典带出(autoFill)、关联带出(linkFill)、公式、别的系统回填。「合同编号带回来了才露这一格」就是这一句
要说清的代价 这一格由人填、又拿自己的值决定露不露:填一个字它就当场藏起来(光标还停在上面,格子已经没了)。值不会丢(见下面「收值那一句」),但界面上这一下确实像被吞了,所以设计器当场把这句话写在那一行下面
要「有值就别让人改」 配的是「满足条件就锁住」(readonlyWhen 判自己 notEmpty),不是显示条件
收值那一句 只被自己那句条件收走 / 锁住的格子,提交时这一笔值照样收下(formruntime.self_gated_keys ↔ formRuntime.writableIgnoringSelf)。否则「有值才显示」「有值就锁住」会把人刚敲的那一笔按「这一环改不动」退回原样,写进去的字凭空消失
一寸没放宽的地方 界面上露不露、必填要不要、阈值 / 额度 / 取数挡不挡人,读的都是带自引用的那一份条件;环节明写隐藏、被别的格子挡住、类型压根没有录入框,三档都不借这一句翻案
级联清值 自指不进这一圈:dependsOn / depends_on 照旧把「自己」摘掉,否则刚写进来那一份会被当成越界值抹掉。conditionDependencies 留着它(设计期检查与界面重算要读)
仍算配错的三句 级联上级选了自己;同一条规则左右两头是同一格(field 与 valueField 同名);指向不存在的字段
改名 那一格自己那几条「判自己」的条件跟着新名字搬(utils/formRename)。别的格子上读旧名字的条件照旧不动——那句看得见,交给人决定
顺手修的分叉 「填没填」这一寸两边不一样:后端 dicts._is_empty 一直把一串空格算没填,前端 isEmptyValue 只认空串。notEmpty 判自己时两边能算出两个结果(界面露出一行空白,服务端判它没填),现在同一把尺子
验收 PYTHONPATH=. python3 scripts/check_self_visible.py(不碰库)+ npx vitest run src/utils/formLinkage.self.spec.ts src/components/oa/FormRenderer.self.spec.ts src/components/oa/design/LinkagePanel.self.spec.ts src/utils/formRename.spec.ts
唯一口径在哪 判法 frontend/src/utils/formLinkage.ts ↔ 后端 backend/app/service/dicts.py;最终权限与收值 frontend/src/utils/formRuntime.ts ↔ backend/app/service/formruntime.py(引擎回滚那一段在 engine._apply_form_runtime);设计器那一栏 components/oa/design/LinkagePanel.vue + LinkageConditionDialog.vue

1. 为什么这一档值得放开

「这一格露不露」以前只能说别人的事:visibleWhen 里挑的字段一定是另一格。可表单上有一整类 格子,它该不该露,问的恰恰是它自己有没有值:

  • 外部取数带回来的合同编号 / 发票号 / 预算余额——带回来了才有脸露出来,没带回来就该一句不说;
  • 别的环节或别的系统回填的补充说明——回填了才看得见,不然摆一行空标签;
  • 明细表 / 附件这种「有了才露」的整片区域,配合「默认隐藏」用得最多(默认隐藏那一档只在 配了显示条件时让位,见 README 里那一段,hidden_by_default)。

绕过去的办法是造一个中间变量:另开一格隐藏的公式 =IF(合同编号<>"",1,""),再让条件去读它。 配的人得多懂一层,多出来的格子还会漏进导出与打印,而条件念出来是「中间值 等于 1」, 没人知道它在说什么。判据本来就够得着自己的值,缺的只是让人把这一格挑出来。

2. 语义只有一条:读的就是这一格此刻的值

没有新引擎、没有「按载入时的值」那一档、也没有「一旦露出来就不再收回」那种粘性状态。 rules[].field === 本字段 就是把本字段当成条件里的普通一格读——compare 那一条路, 两边(前端 utils/formLinkage、后端 service/dicts)本来就跑同一份数据、同一个结果。

为什么不搞粘性(露过一次就留着):那种状态只活在一次打开里,服务端算不出来, 于是「界面让人填、提交说非法」那道缝又回来了。这一整套的底线是同一个条件两边一个结果, 所以宁可让语义是「此刻的值」,把人会踩的那个坑拿到设计器里当场说清(§4)。

3. 放开之后必须钉住的三条

3.1 只放宽「判谁」,不放宽「怎么判」

  • 级联上级(cascadeFrom)选到自己仍是配错:候选得由另一格来筛,自己筛自己筛不出东西;
  • 同一条规则左右两头是同一格({field: x, op: eq, valueField: x})仍是配错:自己跟自己 比没有新意思;
  • 指向不存在的字段照旧报(哪怕同一条条件里还有指向自己的那一条——只放行指自己那一条)。

3.2 自指不进「上游变了清下级失效值」那一圈

dependsOn(depends_on)按定义摘掉自指。这一刀不是遗留:清失效值那一趟会拿 effectiveOptions 反过来质疑刚写进来的那一份值,自己当自己的上游就是「自己判自己越界」, 带出来的值会在一轮收敛里被抹掉。条件层面要不要跟着重算不依赖这一份清单——办理屏那句 hiddenOnScreen 本来就是对着整份 modelValue 算的。

3.3 「只被自己藏起来」的那一笔值要收下

引擎那一段回滚的判据是「这个环节改不动这一格」:

writable = editable_keys(fields, perms, data) | hidden_keys | self_gated_keys(fields, perms, data)

self_gated_keys 问的是「把这一格三栏条件里读自己那几条摘掉以后,它本来就填得动吗」。 是,就收这一笔——因为这一笔值正是让它藏起来的原因,退回原样等于把人刚写的字抹掉。 摘掉以后仍然填不动(环节明写隐藏 / 只读、被别的格子的条件挡住、description 那种 没有录入框的类型),一概不放宽。

放宽的只有「收不收这一笔值」。界面露不露、必填要不要、阈值 / 额度 / 取数挡不挡人, 读的还是带自引用的那一份条件——所以不会出现「后端偷偷多收了一格不该收的值」。

4. 设计器:能挑到、看得懂、错得快

  • 条件清单里本字段排最前面,标成「本字段(contractNo)」;摘要也念成「本字段 已填」, 不会跟表单上另一个同名字段混。
  • 两颗一键开关直接落 notEmpty / empty,不配别的条件时压根不用进弹窗;选中态再点一下撤掉。
  • 挑中自己就在这一行下面多说一句:值由系统写进来的格子是一句平铺说明;这一格由人填时 换成黄字,说清「填一个字它就当场藏起来 / 要『有值就别让人改』请配在『满足条件就锁住』」。
  • 这一格只靠自己的值决定露不露、又是人填的,那句话直接摊在侧栏那一栏下面(gatedBySelfAlone), 不用进弹窗就看得见;系统带出 / 公式那一类格子不提示。
  • 右边那一档(比另一格)里没有自己:partnersOf 按 rule.field 筛,挑了本字段之后 另一头自然只剩别的格子,比不了的那一档压根不给。

5. 老表单

一个字都不动。以前存不出自引用条件(保存就被拦),所以没有存量要迁;conditionDependencies 多出来的那一个自指键只影响设计期检查,而那一处已经从「报错」改成「放行」。

6. 回看那一屏与必填:同一条判据的另一端(2026-11 之后)

放开自引用之后,同一批反馈里冒出来两句互相拧着的:

  1. 「提交流程之后回看页所有字段都显示了。」 回看那一屏(只读渲染:单据详情 / 打印 / 手机完整单据)以前只往宽放——不凭条件收任何格子。少摆一行「存过的值」比多摆一行难发现, 所以那是当年的取舍;代价就是配了「有值才显示」的那些格子,在办结之后整排摊开, 明明这一单用不到它。
  2. 「改成默认隐藏 + 显示条件,表单校验又过不了。」 病根不在显隐,在必填:auto / formula 这两类没有录入框、权限永远算只读,字段自己勾了必填说的是「必须算得出值」。老判据连 因显示条件不成立被收走的那一格一起催「还没填写」——屏幕上没有那一格,提交永远过不去。

两句各改一句,都不碰自引用那一条:

改的那一句 现在怎么说 在哪
回看那一屏摆不摆 环节明写 hidden → 收;环节给了别的权限 → 摊;勾了「默认隐藏」→ 按存过的那份值评条件;没勾默认隐藏、配了显示条件、按存过值评不成立、且这一格为空 → 收。有值一律摊开 前端 formRuntime.readbackHidden(手机端 mobileLayout 继承同一句)
藏起来的格子要不要算必填 只有因显示条件不成立被收走的才算「这一单用不到它」;勾了「默认隐藏」又没配条件的(单据编号、金额大写)藏起来不等于可以不生成 后端 formruntime.hidden_by_condition → missing_required;前端 formRuntime.hiddenByCondition → requiredFields

保留的那一寸写明白:有值但条件已翻走的格子,回看页仍然摊开。那一笔值确实存过, 收起来等于让它凭空消失;真要按存过值全收干净,得再加一颗字段级开关,别默认改。 钉在 formRuntime.hidden.spec.ts、mobileLayout.spec.ts、FormRenderer.self.spec.ts 与 PYTHONPATH=. python3 scripts/check_option_routes.py 第 8 段。