自定义字段:不改代码给单据加栏

给销售订单加一栏「项目号」不必改实体、改表单、改数据库。管理员在维护页选实体、填类型就能加栏,值随记录存进 Extension JSON 槽并由服务端统一校验;删掉定义只是不再显示,重建同名键即可找回。开发者要做的是声明哪些实体可扩展、表单与列表怎么接、引用候选去哪查。

最后更新

客户说「销售订单上要加一栏项目号」。最直觉的做法是给实体加一个属性、给表加一列——但那要改实体、改表单、改保存逻辑,还要处理每个已部署库的增列;更要命的是这一列进了公共代码,所有客户的系统都跟着多一栏没人用的字段。

自定义字段走的是另一条路:定义是一行数据,值是每条记录自己的 Extension JSON 槽。加一栏等于加一行定义,不动表结构、不改核心代码;删掉定义只是不再显示,已经录入的值仍留在库里。

这项能力在框架侧分两层:契约与内核在 Known/FieldKit,字段定义服务与维护页 /base/fielddef 在 Known.Admin。业务项目(例如 ERPLite)只提供三样本项目才知道的事:哪些实体可扩展、哪些字段要预置、引用类型的候选去哪查。

什么时候该用,什么时候不该用

需求 选什么 原因
某几家客户要的机动栏位,比如项目号、客户风险等级、图纸编号 自定义字段 一行定义搞定,不污染公共实体与表结构
要参与合计、排序、筛选、报表分组,或是审批条件里的金额门槛 真列 + 迁移 JSON 槽不是数据库列,聚合与索引都用不上它
要一整套新业务对象,有自己的列表、表单与增删改查 运行时 Schema 那是从零建页面;自定义字段是给已有页面加机动栏
所有客户都必须有、且业务语义固定的字段 真列 它是模型的一部分,不该由实施时配置决定

一句话:自定义字段解决「各客户不一样的一栏」,不解决「所有客户都一样的模型」。

两层数据,一条保存链

层 存在哪 谁读
定义 ErpFieldDef 表,一条字段一行(EntityKey / Name / Label / FieldType / 必填 / 选项…) 维护页、表单渲染、列表扩展列、服务端校验;客户端有缓存
值 被扩展记录自己的 Extension 列(JSON) 读一张单不需要联表;列表与详情按同一套显示规则还原文本

保存时的顺序是固定的:先按定义做类型归一与必填校验 → 引用字段按 Id 刷新显示文本 → 与槽里的原有内容合并 → 写回记录。所以「删掉定义再重建同名键」能把旧值找回来,而「改 Name」会把旧值变成没人认领的孤儿键。

一、管理员:三步加一栏

1. 进维护页,先选实体

侧栏进入「自定义字段」(路由 /base/fielddef,菜单分组为「基础数据 / 主数据」)。页面上方是实体下拉,只列出代码里登记过的可扩展实体——列表里没有的实体,说明它还没接入,不能从这里硬加。

看不到这个菜单,先查当前角色有没有授予「自定义字段」页;字段定义的保存与删除接口也按这个菜单鉴权,不是登录就能改。

2. 点「新增字段」,逐项填写

配置项 怎么填 约束
字段名 Name 英文存储键,例如 projectNo、custRiskLevel 字母起头,只能含字母 / 数字 / 下划线,≤40 字符;一经使用不要改;也不能与实体已有属性同名
显示名 Label 界面上给用户看的中文,例如「项目号」 随便改,不影响历史数据
类型 FieldType 从下拉选,见下表 存的是枚举名(String / Int / …),不要手造字符串
长度上限 仅文本类型出现,0 表示不限 0–2000;不限长的文本在表单里占满整行
选项 仅单选类型出现,格式 high:高风险,medium:中风险,low:低风险 冒号前是存储值,后面是显示名;必须填
引用实体 / 显示字段 仅引用类型出现 引用实体必须是登记过的可扩展实体;显示字段留空时自动取「编码 + 名称」
字段说明 Help 给录入人员的提示 可选
必填 / 在列表里显示 / 启用 三个开关 不想让人再用又不删数据,就把「启用」关掉
列宽 / 排序 勾了「在列表里显示」才出现 列宽如 120px,留空自适应;排序数字越小越靠前

保存后服务端会清掉定义缓存;已经打开的业务页面要刷新一次才会带上新栏位(客户端也缓存了一份定义)。

3. 到业务页看效果

以 ERPLite 为例,演示库已接入六个实体:客户、销售订单、销售订单明细、采购订单、物料、工单。它们的表单里会多出一块「扩展信息」(明细行是行内栏,弹窗档案是两列,整页单据是四列);勾了「在列表里显示」的栏位会自动出现在列表尾部,详情页按同样的顺序和标签只读摊出来。

二、七种类型怎么填

类型 录入控件 额外配置 槽里存的样子
String 文本 输入框 / 不限长时多行 长度上限 "HT-2026-0001"
Int 整数 数字步进器 — 365
Decimal 数值 数字输入框 — 120.5
Bool 是/否 开关 — true / false
DateTime 日期 日期选择器 — "2026-11-18"
Enum 单选 下拉 选项串 "high"(存值,界面显示「高风险」)
Ref 引用 下拉,候选来自业务项目实现 引用实体 + 显示字段 "记录Id\|显示文本快照"

单选:值存英文,界面显示中文

选项写成 值:显示名,多个用逗号分隔(中英文逗号、分号都认):

high:高风险,medium:中风险,low:低风险

历史数据存的是 high 这个键。日后把显示名从「高风险」改成「重点客户」,旧记录不需要迁移;反过来如果改的是冒号前面的值,旧记录就对不上了——值一旦用过就别改,改显示名随便。

引用:选的是记录,存的是 Id + 文本快照

引用字段的下拉候选由业务项目实现 IRefOptionsProvider 提供。选中后写入的是 Id|显示文本:

  • 列表和详情直接读那段文本快照,不必为了显示一个名字去联目标表;
  • 服务端保存时会按 Id 重新取一次当前显示文本,所以被引记录改了名,这里能跟着变;
  • 如果业务项目没注册这个端口,候选是空的,保存时会明确拒绝——框架不会去猜一张业务表。

引用的目标实体也必须在可扩展白名单里,否则维护页保存定义时就会拦下来。

三、录入人员看到什么

  • 表单:「扩展信息」区的控件由类型自动决定,不需要为每个字段写页面代码。必填字段空着会在客户端标红,服务端还会再校验一次(直接调接口也绕不过去)。
  • 列表:勾了「在列表里显示」的栏位追加在列表里,单选显示中文、引用显示文本、未填显示「—」。
  • 详情:只读展示,顺序和标签与录入表单一致。
  • 清空一栏:留空就是清掉这个值,不是「没提交」。

一个槽里所有有效值的 JSON 上限是 16 KB。超了会给出明确报错,这时候该拆成真列或独立页面,而不是继续往槽里塞。

四、开发者:给一个新实体接上自定义字段

框架不会默认放开所有实体——[Extensible] 是显式 opt-in。要让某类单据能挂字段,做下面几件事。

框架提供的是内核与契约(定义、校验、缓存、列表助手与 Ref 端口);表单组件与命名由宿主自己封装。下面的 ErpExtFields / ErpExtColumns / ErpRefs 是 ERPLite 的封装名,其他项目换成自己的实现即可,步骤不变。

1. 实体打标

[Table("biz_Project")]
[Extensible("项目")]          // 参数是维护页下拉里的显示名,留空则取 [DisplayName]
public class Project : EntityBase { ... }

实体必须继承 EntityBase 且有无参构造。键取实体上的表名,它同时是维护页下拉的值、FieldDef.EntityKey 和反射定位类型的依据。框架内部表(Sys*)不要打这个标。

2. 表单放组件

<ErpExtFields @ref="extFields"
              EntityKey="@nameof(Project)"
              Extension="@model.Extension"
              Columns="2" />   @* 整页单据可省略,默认 4;弹窗档案传 2 *@

组件会自动拉定义、拉引用候选、按类型渲染控件。详情只读页传 ReadOnly="true" 即可用同一套布局展示。

3. 保存走两条路

单据头走侧信道——先存主记录拿到主键,再把扩展值单独写进去:

var saved = await Svc.SaveAsync(model);
var result = await extFields.SaveAsync(FieldExtension.IdOf(saved));   // 没带回主键会明确报错,不会静默丢值

SaveAsync 在没有配任何字段时返回 null,调用方要区分「不需要保存」和「保存失败」。

明细行必须跟着主记录一起落库,用 ToExtension() 把当前编辑值写回每一行的 Extension 槽,服务端再做逐行归一化:

var lines = rows.Select(x => { x.Extension = lineExtFields.ToExtension(); return x; }).ToList();

新建单据的整条链路都靠保存接口回传主键,所以这一步不能跳过。

4. 列表追加扩展列

extColumns = await ErpExtColumns.LoadAsync(FieldSvc, nameof(Project));
@foreach (var def in ErpExtColumns.Visible(extColumns))
{
    <Column TItem="Project" Title="@def.Label" Field="@def.Name" Width="@def.Width">
        <span class="text-muted">@ErpExtColumns.TextOf(def, context)</span>
    </Column>
}

TextOf 与表单详情用的是同一套显示规则,不会出现「录入页显示中文、列表显示英文代码」。

5. 引用端口只在服务端注册

// 宿主装配里:客户端没有 Database,注册进去会在 DI 构造时炸掉
if (!clientSide)
    services.AddScoped<IRefOptionsProvider, ProjectRefs>();

实现两个方法:GetOptionsAsync(entityKey, displayField, keyword) 返回候选,ResolveTextAsync(entityKey, id, displayField) 按 Id 返回当前显示文本。候选要带搜索关键字与上限,别一次把整张档案表拉回来。

6. 预置字段定义(可选)

需要随版本预置一批字段时,在拥有该实体的插件 XxxSetup 里声明,启动时由框架补缺:

public ProjectSetup() : base("project", ErpGroups.Project)
{
    Field("Project", "projectNo", "项目号", nameof(SchemaFieldType.String),
          textLength: 40, showInList: true, width: "140px", sort: 10);
}

播种统一走 AdminSeed.EnsureAsync(db, PluginSetups.FieldsFor(...), idOf)。它只补缺、不覆盖——用户在维护页改过的显示名、排序、启停不会被重启刷回去。主键口径由调用方决定,多账套项目要带账套前缀。

五、红线与排错

现象 原因与处理
改了 Name,历史值全不见了 Name 是 JSON 键,改名等于孤立旧值。把键改回去,或重建同名定义
维护页提示「与已有字段重名」 定义名不能撞实体上的真实属性。加个前缀,例如 custRiskLevel
想把这个字段挪到别的实体 不允许。删掉后在目标实体重建;跨实体搬定义会让原记录的值没人认领
单选列表显示英文代码 检查选项串的写法是不是 值:显示名,以及显示是否绕过了 TextOf / FieldExtension.Text
引用下拉是空的 服务端没注册 IRefOptionsProvider,或者目标实体不在可扩展白名单里
新字段保存了但页面没出现 已打开的页面还端着旧的定义缓存,刷新一次
提示超过 16 KB 槽不是大字段容器,把长内容拆到真列或独立页面
想按自定义字段统计 / 筛选 做不到,也不该做。这类需求改建真列并写迁移
停用一个字段后又想恢复 打开「启用」开关即可;删除定义不会删值,但会连显示规则一起丢掉

和运行时 Schema 的分工

运行时 Schema 自定义字段
解决什么 从零生成一整套列表 + 表单 + CRUD 页面 给已有实体加几家客户才要的栏
载体 一份 *.schema.json 定义表一行 + 记录的 Extension 槽
值存哪 实体的真列 JSON 槽,不建列
能否参与查询聚合 能(真列) 不能

两者不冲突:一套系统可以用 Schema 快速搭出标准页面,再用自定义字段吸收各客户的差异需求。


维护页右上角的帮助按钮(页内 ?)提供的是精简操作提示;完整口径以本文为准。框架能力更新时只需维护这一篇,页内提示保持简短,避免两处长文互相打架。

微信公众号二维码 扫码关注公众号
QQ 交流群二维码 扫码加入 QQ 群