首页 / 开发手册 / 字段引擎

字段引擎

字段 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 格式、同一个渲染器、同一个校验器。 新增一种字段类型时,两处会同时获得这种能力,不存在两套并行逻辑 —— 所以你在「内容模型」里加了一个类型,留言表单那边立刻也能用。

校验发生在哪里

  1. 表单:前端做基础校验,提升体验
  2. 服务端:重新按 schema 逐字段校验,不信任任何前端提交
  3. 入库前:下拉与单选的值如果不在选项列表里,直接丢弃,避免脏数据

第三点值得强调:即使有人手工构造请求塞进一个不存在的选项值,也不会被写进数据库。

增加一种字段类型

在 core/Field.php 的 TYPES 注册表里加一项 (格式是 '类型名' => [中文名, 是否多值, 可否筛选]), 然后补上它的渲染分支与校验分支即可,内核其它地方不需要改动 —— 模板层不必理解具体类型,它拿到的是一段已经渲染好的控件 HTML。

⚠️ 加类型之后要清一次模板缓存吗?不用(模板本身没变)。 但前台如果有页面缓存,改完模型要清一次整页缓存 —— 否则老页面还是按旧字段渲染的。

没找到答案? 可以在 联系我们 留言说明使用场景,我们会补充进文档。