客户说「销售订单上要加一栏项目号」。最直觉的做法是给实体加一个属性、给表加一列——但那要改实体、改表单、改保存逻辑,还要处理每个已部署库的增列;更要命的是这一列进了公共代码,所有客户的系统都跟着多一栏没人用的字段。
自定义字段走的是另一条路:定义是一行数据,值是每条记录自己的 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 群