字段引擎
字段 schema 的格式、校验规则,以及怎么增加一种新的字段类型。
一句话说清它是什么
内容模型就是「一张字段定义表」。你加字段、改字段,不需要动数据库结构,
也不会有 ALTER TABLE 的迁移风险 —— 值统一存在 contents.ext_data 这个 JSON 列里。
这是它与老一代 CMS 最主要的差别:那边加一个字段就是一次改表。
schema 格式
{
"fields": [
{"key":"price", "label":"价格", "type":"number", "required":true, "filter":true},
{"key":"brand", "label":"品牌", "type":"select", "options":["甲","乙"]},
{"key":"gallery","label":"图集", "type":"images"}
]
}
字段属性
| 属性 | 说明 |
|---|---|
key | 字段标识。小写字母开头,30 字符内,不能与内置字段重名 |
label | 显示名称,最长 40 字 |
type | 字段类型,见下面那张表 |
required | 是否必填 |
options | 选项值,最多 50 个(select/radio/checkbox 用) |
default | 新建内容时的默认值 |
hint | 输入框下方的填写提示 |
filter | 是否参与前台查询。只有部分类型支持(见下表最后一列) |
15 种内置字段类型
type | 名称 | 多值 | 可参与筛选 |
|---|---|---|---|
text | 单行文本 | — | ✅ |
textarea | 多行文本 | — | — |
number | 数字 | — | ✅(按数值比较) |
select | 下拉选择 | — | ✅ |
radio | 单选按钮 | — | ✅ |
checkbox | 多选 | ✅ | ✅ |
switch | 开关 | — | ✅ |
date | 日期 | — | ✅ |
datetime | 日期时间 | — | ✅ |
image | 单张图片 | — | — |
images | 图片组 | ✅ | — |
file | 附件 | — | — |
richtext | 富文本 | — | — |
tags | 标签 | ✅ | ✅ |
relation | 关联内容 | ✅ | — |
「多值」= 这个字段存的是一个数组(多选、图片组、多标签、多关联),
模板里要用 {naicha:loop} 展开。「可参与筛选」= 能写进
{naicha:list field="…"} 的筛选条件。
值存在哪:一份 JSON + 一张索引表
contents.ext_data → {"price":"1280","brand":"甲","gallery":[…]} (唯一事实来源)
content_field_index → (content_id, fkey, num_value, str_value) (筛选用的索引)
为什么需要那张索引表:筛选不能靠 json_extract ——
产品要兼容的 SQLite 是 3.7(2013 年),没有 JSON1 扩展。
所以保存内容时,把「勾了可筛选」的字段值同步写一份到索引表里,
筛选走 EXISTS 子查询:既能比较数字,也能用上索引,还不绑定 SQLite 版本。
⚠️ 这意味着改模型的 filter 勾选之后,已有内容需要重建一次索引
(否则老内容的这个字段在索引表里没有行,筛不出来)。
改完模型保存时会自动回填;这也是为什么"升级后第一次打开"偶尔会看到"已回填 N 条内容的字段索引"。
模板里怎么用
<!-- 直接写字段名就行:引擎在同名列找不到时会自动去 ext 里找 -->
{naicha:detail}
<span>价格:{detail.price} 元</span>
<span>品牌:{detail.brand}</span>
<!-- 多值字段要展开 -->
{naicha:loop from="detail.gallery" as="g"}
<img src="{g.url}" alt="{g.alt}">
{/naicha:loop}
{/naicha:detail}
<!-- 下面这两种写法等价,前一种更好写 -->
{list.media_type} {list.ext.media_type}
按自定义字段筛选
{naicha:list name="product" field="price" op="gt" fvalue="1000" num="8"}
<a href="{list.url}">{list.title} — {list.price} 元</a>
{/naicha:list}
op | 含义 |
|---|---|
eq | 等于(默认) |
neq | 不等于 |
gt / lt | 大于 / 小于 |
gte / lte | 大于等于 / 小于等于 |
数字字段按数字比较大小(9 不会排到 100 后面);
只有模型里勾了「可筛选」的字段能这样查,没勾的字段查不出东西(不报错,就是空)。
接口里怎么取
内容输出接口把自定义字段放在 ext 对象里,按模型定义展开,
调用方不用猜字段名:
GET /api/open/v1/content/my-product
{"code":0,"data":{"id":12,"title":"…","ext":{"price":"1280","brand":"甲"}}}
内置字段名是保留的
以下名字已被内容主表占用,不能用作自定义字段标识:
id cid model title alias summary content thumb ext_data
hits top sort status publish_time author_id
created_at updated_at reject_reason url
另外 need_level(会员门槛)与 files(内容级附件)是后加的列,同样保留。
一套 schema,两处使用
内容模型和自定义表单共用同一份 schema 格式、同一个渲染器、同一个校验器。 新增一种字段类型时,两处会同时获得这种能力,不存在两套并行逻辑 —— 所以你在「内容模型」里加了一个类型,留言表单那边立刻也能用。
校验发生在哪里
- 表单:前端做基础校验,提升体验
- 服务端:重新按 schema 逐字段校验,不信任任何前端提交
- 入库前:下拉与单选的值如果不在选项列表里,直接丢弃,避免脏数据
第三点值得强调:即使有人手工构造请求塞进一个不存在的选项值,也不会被写进数据库。
增加一种字段类型
在 core/Field.php 的 TYPES 注册表里加一项
(格式是 '类型名' => [中文名, 是否多值, 可否筛选]),
然后补上它的渲染分支与校验分支即可,内核其它地方不需要改动 ——
模板层不必理解具体类型,它拿到的是一段已经渲染好的控件 HTML。
⚠️ 加类型之后要清一次模板缓存吗?不用(模板本身没变)。 但前台如果有页面缓存,改完模型要清一次整页缓存 —— 否则老页面还是按旧字段渲染的。
