自定义字段使用教程
自定义字段使用教程
自定义字段用于给文档、分类、标签、用户、城市分站、留言、模板设置和订单附加业务字段,而不需要修改程序代码。
安企CMS 3.8.x 内置 18 种字段类型,共有 9 个位置可以配置自定义字段。本文按「先认识字段、再选择位置、最后按类型设置和调用」的顺序说明。
说明:如果把「商品定制订单字段」和「沟通订单字段」合并看作订单字段,也可以理解为 8 类配置场景。两者作用对象和后台入口不同,本文分开说明,因此按 9 个位置展开。
入口路径
自定义字段没有统一入口,按配置位置分别进入。以下入口均需要管理员权限(canAdmin):
| 字段位置 | 后台入口 | 实际地址 |
|---|---|---|
| 文档字段、分类字段 | 内容 → 内容模型 → 修改 | /system/archive/module |
| 标签字段 | 内容 → 文档标签 → 自定义字段 | /system/archive/tag |
| 用户字段 | 用户管理 → 用户附加字段设置 | /system/plugin/commerce/user |
| 城市分站字段 | 内容 → 城市管理 → 城市分站设置 | /system/archive/place |
| 留言字段 | 网站留言管理 → 网站留言设置 | /system/plugin/interaction/guestbook |
| 模板内容设置 | 设计 → 模板内容设置 | /system/design/diyfield |
| 商品定制订单字段 | 产品编辑页 → 定制商品 → 定制订单字段管理 | /system/product/detail?id=<产品ID> |
| 沟通订单字段 | 沟通订单 → 订单设置 | /system/order/communication |
功能说明
自定义字段用于扩展文档、分类、标签、用户、城市分站、留言、模板设置和订单的数据结构,无需改代码即可增加字段并在模板或接口中使用。字段值一部分存为真实数据库列(文档字段、用户字段),一部分存为 JSON(其余位置),调用方式因此不同。
界面截图
下文各配置位置均配有当前后台截图,包括字段类型选择弹窗、内容模型、标签、用户、城市分站、留言、模板内容设置、商品定制订单字段和沟通订单字段。

设置项说明
| 设置项 | 作用 | 取值 / 默认 | 怎么选 / 填写建议 | 影响 / 注意 |
|---|---|---|---|---|
| 参数名称 | 后台显示的名称 | 文本,无默认 | 写便于识别的中文名 | — |
| 调用字段 | 数据库列名与模板调用名 | 字母开头的英文标识 [源码] | 用小写字母、数字、下划线 | 有数据后不可改名 |
| 字段类型 | 决定输入控件与存储格式 | 18 种类型 [源码] | 按数据形态选,见第三章 | 创建后不可改类型 |
| 默认值 | 无输入时的初始内容 | 按类型而定 | 单选/多选的默认值即选项配置 | 多选值在文档中是逗号分隔字符串 |
| 是否必填 | 提交时是否强制填写 | 是 / 否 | 按业务要求设置 | 部分位置后台强制为否 |
常见配置项包括参数名称、调用字段、字段类型、默认值和是否必填;部分位置还支持筛选、跟随阅读等级等选项。逐项说明见「1.1 字段配置项」,支持的类型见「三、18 种字段类型详解」。
操作步骤
- 按「二、9 个可配置位置」找到对应后台入口。
- 添加字段,填写参数名称、调用字段、字段类型和默认值。
- 保存后到对应的内容编辑页填写字段值。
- 按「四、模板调用速查」在模板中调用,或通过接口读取。
注意事项
- 调用字段一旦有数据不要改名,文档字段和用户字段同时是数据库列名。
- 字段类型变更后旧值不会自动转换,建议新增字段并迁移数据。
- 模板内容设置的参数名保存时会自动首字母大写,调用时大小写必须一致。
- 多选值在不同位置的存储格式不同,详见「五、常见问题与注意事项」。
相关文档
一、先理解字段的 3 个关键点
1.1 字段配置项
在后台添加自定义字段时,常见的配置项如下:
| 配置项 | 说明 | 注意事项 |
|---|---|---|
| 参数名称 | 显示给管理员和访问者的名称,如「作者」「来源」 | 中文即可,会显示在表单和部分模板循环中 |
| 调用字段 | 字段的**标识,用于建表、模板调用、接口字段名和 URL 参数 | 除「模板内容设置」外,必须以小写英文字母开头,只能包含小写字母、数字和下划线,建议使用 ^[a-z][0-9a-z_]+$ 的形式 |
| 字段类型 | 决定录入组件、存储方式和模板输出类型 | 文档和用户字段创建后,后台不允许再修改类型 |
| 默认值 / 选项 | 普通类型作为默认值和输入提示;单选、多选、下拉类型作为选项列表 | 选项一行一个,空行会被忽略 |
| 是否必填 | 要求提交时必须有值 | 是否真正生效取决于所在位置,见 2.1 的表格 |
| 作为筛选参数 | 允许该字段参与文档列表筛选 | 只对文档字段生效,且只有单选、多选、下拉类型可用 |
| 跟随文档阅读等级 | 用户未购买或阅读等级不足时,不输出该字段 | 只对文档字段生效 |
| 模块组 | 给模板自定义字段分组 | 仅「模板内容设置」使用 |
| 备注 | 字段的补充说明 | 仅「模板内容设置」使用 |
调用字段一旦有数据,就不要随意改名。文档字段和用户字段的调用字段同时是数据库列名,改名相当于换了一个字段,旧数据不会自动迁移。部分入口(如模板内容设置)把这一项显示为「参数名」,含义相同。
模板内容设置的参数名会在保存时自动把首字母大写,模板调用时必须使用大写后的完整名称。例如参数名填写 SitePhone,模板中要写 name="SitePhone"。
1.2 两种存储方式
不同位置的自定义字段,底层存储方式不同:
| 存储方式 | 涉及位置 | 影响 |
|---|---|---|
| 真实数据库列 | 文档字段、用户字段 | 添加字段会执行 ALTER TABLE ... ADD COLUMN;删除字段会删除列和列中的数据;字段类型决定列类型 |
| JSON 文本 | 分类、标签、城市分站、留言、模板内容设置、商品定制订单、沟通订单 | 不新增数据库列;删除字段只删除配置,旧 JSON 数据会留在原记录中 |
因此,文档字段和用户字段的操作风险明显更高,删除前必须确认数据已经备份。
1.3 字段值什么时候使用默认值
除单选、多选、下拉三种类型外,当字段没有填写值时,系统会在读取阶段用「默认值 / 选项」的内容补位。单选、多选、下拉不会自动补默认值,未选择时就是空值。
二、9 个可配置位置
2.1 位置总览
| 位置 | 后台入口 | 作用范围 | 存储 | 支持类型数 | 必填校验 |
|---|---|---|---|---|---|
| 文档字段 | 内容 → 内容模型 → 编辑模型 → 文档自定义字段 | 该模型下的所有文档 | 模型表列 | 18 | 后台整表单保存时校验 |
| 分类字段 | 内容 → 内容模型 → 编辑模型 → 分类自定义字段 | 该模型下的所有分类 | categories.extra JSON |
18 | 不强制 |
| 标签字段 | 内容 → 文档标签 → 自定义字段 | 所有文档标签 | tag_contents.extra JSON |
13 | 不强制 |
| 用户字段 | 功能 → 用户/交易 → 用户管理 → 设置 → 额外字段 | 所有用户 | users 表列 |
13 | 后台强制关闭 |
| 城市分站字段 | 内容 → 城市管理 → 设置 → 自定义字段 | 所有城市分站 | places.extra JSON |
13 | 不强制 |
| 留言字段 | 功能 → 互动/留言 → 网站留言管理 → 设置 → 字段 | 留言表单 | guestbooks.extra_data JSON |
8 | 提交时校验 |
| 模板自定义字段 | 设计 → 模板内容设置 | 全站模板变量 | 站点设置 JSON | 13 | 无必填配置 |
| 商品定制订单字段 | 产品 → 编辑产品 → 定制订单 | 当前定制商品的下单表单 | archive_products.order_fields JSON |
17 | 由前台表单校验 |
| 沟通订单字段 | 订单 → 沟通订单 → 设置 → 自定义订单字段 | 全站沟通定制订单 | 站点设置 JSON | 17 | 由前台表单校验 |
2.2 文档字段
文档字段是最常用的一类,字段会真实添加到内容模型对应的数据表中。
设置步骤:
- 进入「内容 → 内容模型」,编辑目标模型。
- 在「文档自定义字段」中点击「添加字段」。
- 填写参数名称、调用字段、字段类型、默认值和是否必填。
- 保存模型后,发布或编辑该模型下的文档,即可在文档表单中看到新字段。

模板调用:
{# 直接输出单个字段 #}
{% archiveDetail with name="author" %}
{# 先赋值再使用 #}
{% archiveDetail author with name="author" %}
<p>作者:{{ author }}</p>
{# 按模型字段顺序遍历全部字段 #}
{% archiveParams params with sorted=true %}
{% for item in params %}
<p>{{ item.Name }}:{{ item.Value }}</p>
{% endfor %}
{% endarchiveParams %}
文档列表需要读取自定义字段时,给 archiveList 加上 showExtra=true:
{% archiveList archives with moduleId=1 showExtra=true %}
{% for archive in archives %}
<a href="{{ archive.Link }}">{{ archive.Title }}</a>
<span>作者:{{ archive.Extra.author.Value }}</span>
{% endfor %}
{% endarchiveList %}
接口调用:
GET /api/archive/detail:data.extra.{调用字段}.value是字段值。GET /api/archive/list:需要加showExtra=1,结构同样是extra.{调用字段}.value。- 文档列表筛选:URL 参数名直接使用调用字段,例如
?author=张三;多值用英文逗号分隔。
注意事项:
- 添加字段会给模型表加列,数据量大时建议在低峰期操作。
- 后台禁止修改已创建字段的调用字段和类型,因为这会与数据库列定义脱节。
- 删除字段会执行
DROP COLUMN,该列数据会一起删除。
2.3 分类字段
分类字段属于内容模型,但值是保存在分类记录的 JSON 中,不会新增数据库列。
设置步骤:
- 进入「内容 → 内容模型」,编辑目标模型。
- 在「分类自定义字段」中点击「添加字段」。入口与文档字段在同一个模型设置弹窗中,见上图下半部分。
- 保存模型后,编辑该模型下的分类,填写分类字段。
模板调用:
{# 直接读取单个分类字段 #}
{% categoryDetail with name="industry" %}
{# 读取全部分类字段 #}
{% categoryDetail extras with name="extra" %}
{% for item in extras %}
<p>{{ item.Name }}:{{ item.Value }}</p>
{% endfor %}
注意事项:
- 分类字段的 18 种类型与文档字段相同,但值是 JSON,删除字段不会删除数据库列。
- 分类字段不参与
archiveFilters筛选,作为筛选参数对分类字段没有实际效果。 - 分类字段的「跟随文档阅读等级」同样不会生效,它只服务于文档字段。
2.4 标签字段
标签字段用于给标签补充介绍、图标、关联内容等信息。
设置步骤:
- 进入「内容 → 文档标签」。
- 点击页面上的「自定义字段」按钮。
- 添加字段并保存。
- 编辑任意标签,在标签表单中填写字段值。

模板调用:
{% tagDetail with name="brand_story" %}
{% tagDetail extras with name="extra" %}
{% for item in extras %}
<p>{{ item.Name }}:{{ item.Value }}</p>
{% endfor %}
注意事项:
- 标签字段的调用字段会与
tags表已有列做冲突检查,不能与系统列同名。 - 标签字段保存在
tag_contents.extra,删除字段不会影响已有标签的其他数据。 - 标签字段支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。
2.5 用户字段
用户字段用于保存会员的公司、职位、行业、资质等扩展资料。
设置步骤:
- 进入「功能 → 用户/交易 → 用户管理」。
- 点击「设置」,在弹窗中找到「额外字段」。
- 添加字段并保存。
- 在用户编辑页或注册表单中填写字段值。

模板调用:
{# 读取当前登录用户的扩展字段 #}
{% userDetail with name="company" %}
{# 读取指定用户 #}
<p>公司:{% userDetail with name="company" id=8 %}</p>
注册接口也支持提交用户扩展字段:在 /api/register 的 JSON 中直接使用调用字段作为键,例如 {"user_name": "demo", "company": "示例公司"}。
注意事项:
- 用户字段会添加到
users表,属于真实数据库列;删除字段会删除列和数据。 - 后台保存用户字段时会强制把「是否必填」设为否,必填只在自定义的前台表单中自行校验。
- 用户字段支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。
2.6 城市分站字段
城市分站字段用于给每个分站补充地址、电话、营业时间、门店图片等信息。
设置步骤:
- 进入「内容 → 城市管理」。
- 点击「设置」,在「自定义字段」中添加字段。
- 编辑具体城市分站时填写字段值。

模板调用:
{% placeDetail with name="phone" %}
{% placeDetail extras with name="extra" %}
{% for item in extras %}
<p>{{ item.Name }}:{{ item.Value }}</p>
{% endfor %}
注意事项:
- 城市分站字段保存在
places.extra,属于 JSON 存储。 - 支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。
- 分站字段适合放门店信息;需要按城市筛选内容时,请使用城市分站本身的关联能力,而不是字段筛选。
2.7 留言字段
留言字段用于自定义留言表单,例如「公司名称」「预算范围」「需求类型」。
设置步骤:
- 进入「功能 → 互动/留言 → 网站留言管理」。
- 点击「设置」,在字段列表中维护留言字段。
- 前台留言模板通过
guestbook标签渲染表单。

默认字段包括 user_name、contact、email、qq、whatsapp、content。如果后台没有配置任何留言字段,系统会自动补上这组默认字段。
模板调用:
<form action="/guestbook.html" method="post" enctype="multipart/form-data">
{% guestbook fields %}
{% for item in fields %}
<label>{{ item.Name }}</label>
{% if item.Type == "text" || item.Type == "number" %}
<input type="{{ item.Type }}" name="{{ item.FieldName }}" {% if item.Required %}required{% endif %} placeholder="{{ item.Content }}">
{% elif item.Type == "textarea" %}
<textarea name="{{ item.FieldName }}" {% if item.Required %}required{% endif %}></textarea>
{% elif item.Type == "radio" %}
{% for val in item.Items %}
<label><input type="radio" name="{{ item.FieldName }}" value="{{ val }}">{{ val }}</label>
{% endfor %}
{% elif item.Type == "checkbox" %}
{% for val in item.Items %}
<label><input type="checkbox" name="{{ item.FieldName }}[]" value="{{ val }}">{{ val }}</label>
{% endfor %}
{% elif item.Type == "select" %}
<select name="{{ item.FieldName }}">
{% for val in item.Items %}
<option value="{{ val }}">{{ val }}</option>
{% endfor %}
</select>
{% elif item.Type == "image" || item.Type == "file" %}
<input type="file" name="{{ item.FieldName }}" {% if item.Required %}required{% endif %}>
{% endif %}
{% endfor %}
{% endguestbook %}
<button type="submit">提交</button>
</form>
注意事项:
- 留言字段只支持 8 种类型:单行文本、数字、多行文本、单选、多选、下拉、单图、文件。
- 多选字段提交时字段名要加
[],服务端会把多个值合并成英文逗号分隔的字符串。 - 图片和文件字段会先上传到附件库,再把地址写入留言扩展数据。
- 必填校验在留言提交时执行,未填会返回「XXX必填」。
2.8 模板自定义字段(模板内容设置)
模板自定义字段不隶属于某个内容,而是全站共享的键值,适合放客服电话、备案号、公司地址、统一的活动图等。
设置步骤:
- 进入「设计 → 模板内容设置」。
- 点击添加字段,填写参数名、备注、模块组、字段类型和默认值。参数名保存时首字母会自动大写,建议直接使用
SitePhone这样的形式。 - 模块组用于把字段分成多个标签页,例如「基础信息」「联系方式」。

模板调用时名称大小写必须与后台一致:
{# 输出单个字段 #}
{% diy with name="SitePhone" %}
{# 先赋值再使用 #}
{% diy sitePhone with name="SitePhone" %}
<a href="tel:{{ sitePhone }}">{{ sitePhone }}</a>
注意事项:
- 模板自定义字段必须通过
name指定调用字段,不能直接遍历。 - 支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。历史数据中已经存在的颜色等类型字段仍可正常显示和编辑。
- 修改字段配置后如果前台没有变化,请清理缓存。
2.9 商品定制订单字段
定制商品可以要求买家在下单后补充定制信息,例如刻字内容、尺寸、参考图片。
设置步骤:
- 进入「产品」,编辑目标产品。
- 打开「定制订单」。
- 在「定制订单字段管理」中添加字段并保存。
- 买家支付成功后,系统会引导其进入
/order/custom_form填写定制信息。

相关接口:
GET /api/order/detail:订单详情的details[].order_fields是字段定义,details[].order_extra是已填写的值。GET /api/order/custom_form:获取待填写的定制表单。POST /api/order/custom_form:提交定制信息,字段值放在details[].order_extra中。
注意事项:
- 只有产品类型为「定制」时,订单字段才会保存;切回普通商品后,已有订单字段定义会被清空。
- 支持 17 种类型,不支持动态时间线。
- 订单详情读取的是当前商品和订单上的字段定义,修改字段名称会影响历史订单的表单回显,但历史
order_extra中的旧键值不会自动改名。
2.10 沟通订单字段
沟通定制订单用于先沟通需求、后报价的场景,字段在全局设置中配置,所有沟通订单共用。
设置步骤:
- 进入「订单 → 沟通订单」。
- 打开设置,在「自定义订单字段」中添加字段。
- 买家创建沟通订单时填写这些字段。

相关接口:
GET /api/communication/fields:获取沟通订单字段定义。POST /api/communication/order/create:创建沟通订单,字段值放在order_extra中。GET /api/communication/order/detail:返回order_fields和order_extra。
注意事项:
- 支持 17 种类型,不支持动态时间线。
- 字段定义来自全局设置,修改设置后所有沟通订单的表单会一起变化。
- 必填由前台表单和接口调用方保证,后台保存字段配置时不做强制校验。
三、18 种字段类型详解
后台添加文档字段时,字段类型选择如下图所示:

以下示例默认使用「文档字段」的遍历方式:
{% archiveParams params with sorted=true %}
{% for item in params %}
{{ item.Name }}:{{ item.Value }}
{% endfor %}
{% endarchiveParams %}
如果字段加在分类、标签、城市分站或模板设置中,把取值标签换成对应的 categoryDetail、tagDetail、placeDetail 或 diy 即可。
3.1 单行文本 text
用于保存一行短文本,例如作者、来源、型号、编号。
设置:字段类型选择「单行文本」;「默认值 / 选项」填写默认值,同时会作为后台输入框的提示文字。
输出:字符串。
{% archiveDetail with name="author" %}
适用场景:作者、来源、品牌、型号、证件编号、短标签。
注意事项:
- 文档字段和用户字段对应
varchar(190),建议控制在 190 个字符以内。 - 电话、身份证号等需要保留前导 0 或非数字字符的内容,不要使用数字类型,应改用单行文本,并避免参与数值计算。
- 不能换行,需要多行请使用多行文本。
3.2 数字 number
用于保存整数,例如年份、数量、面积、库存。
设置:字段类型选择「数字」;「默认值 / 选项」填写默认数字。后台使用数字输入框。
输出:整数。
{% archiveDetail year with name="year" %}
{% if year > 2020 %}
较新的内容
{% endif %}
适用场景:年份、数量、面积、评分、排序权重、库存。
注意事项:
- 文档字段和用户字段对应
int(10),只保存整数,不支持小数。 - 不要用于电话号码、邮编、身份证号;前导 0 会丢失。
- 数字字段不能设置为筛选参数。
3.3 多行文本 textarea
用于保存多行纯文本,例如地址、备注、规格说明。
设置:字段类型选择「多行文本」;「默认值 / 选项」填写默认值或输入提示。
输出:带换行符的字符串。
<div style="white-space: pre-wrap">{{ item.Value }}</div>
适用场景:详细地址、备注、售后说明、参数说明、简短介绍。
注意事项:
- 不解析 HTML 和 Markdown,换行需要靠 CSS
white-space: pre-wrap或<pre>保留。 - 需要图文混排时请使用富文本类型。
3.4 富文本 / Markdown editor
用于保存带格式的长内容。
设置:字段类型选择「富文本」。当站点内容编辑器设置为 Markdown 时,后台会使用 Markdown 编辑器,前台读取时会把 Markdown 渲染成 HTML。
输出:HTML 字符串(Markdown 模式下且 render=true 时)或原始文本。
{% archiveDetail detail with name="detail" %}
{{ detail|safe }}
适用场景:产品详情、图文介绍、活动说明、长篇补充内容。
注意事项:
- 输出 HTML 时必须加
|safe,否则会显示转义后的标签。 - 只应允许可信管理员编辑该字段,避免把用户提交的内容直接按 HTML 输出。
- 文档字段对应该类型使用
longtext,容量较大,但不适合存放附件本体。
3.5 单选 radio
用于从一组选项中选一个。
设置:字段类型选择「单选」;「默认值 / 选项」一行写一个选项,例如:
现货
预售
缺货
输出:字符串。
{% if item.Value == "现货" %}
<span class="in-stock">现货</span>
{% endif %}
适用场景:状态、是否推荐、成色、等级、性别、配送方式。
注意事项:
- 选项值就是最终保存的文本,修改选项文案后,旧数据仍保留旧文案。
- 未选择时不会自动使用默认值。
- 可以设置为筛选参数,选项会出现在
archiveFilters的筛选条件中。
3.6 多选 checkbox
用于从一组选项中选多个。
设置:字段类型选择「多选」;「默认值 / 选项」一行一个选项。
后台录入:在后台表单中直接勾选,提交时按数组传递;在留言模板中字段名需要带 []。
输出:可能是英文逗号分隔的字符串,也可能是数组,取决于写入入口:
- 文档字段、用户字段、留言字段:保存为英文逗号分隔字符串。
- 分类、标签、城市分站、模板自定义字段:通常按后台提交的数组保存。
{# 文档、用户、留言场景:按逗号拆分 #}
{% for tag in item.Value|split:"," %}
<span>{{ tag }}</span>
{% endfor %}
适用场景:适用人群、功能标签、服务范围、多选偏好。
注意事项:
- 文档、用户、留言场景下,模板中拿到的是逗号分隔字符串,直接输出会显示成
A,B,C。 - 分类、标签、城市分站、模板自定义字段下,模板中拿到的是数组,可直接
for循环。 - 可以设置为筛选参数,多个筛选值用英文逗号分隔。
3.7 下拉选择 select
用于从一组选项中选一个,交互上与单选类似,但占用空间更小。
设置:字段类型选择「下拉选择」;「默认值 / 选项」一行一个选项。
输出:字符串。
<p>所属行业:{{ item.Value }}</p>
适用场景:行业、城市、单位、分类枚举、规格。
注意事项:
- 选项较多时优先使用下拉选择。
- 可以设置为筛选参数。
- 修改选项文案后,旧数据不会自动更新。
3.8 单图 image
用于保存一张图片的地址。
设置:字段类型选择「单图」;后台上传图片后保存附件路径。
输出:字符串形式的图片 URL。
{% if item.Value %}
<img src="{{ item.Value }}" alt="{{ item.Name }}">
{% endif %}
适用场景:封面图、证书、头像、门店照片、图标。
注意事项:
- 保存的是附件地址;切换存储或域名后,系统会在读取时补全存储地址。
- 图片字段只保存一张图,多图请使用组图类型。
- 删除附件库中的文件会导致前台图片失效。
3.9 组图 images
用于保存多张图片,例如画廊、案例图、产品细节图。
设置:字段类型选择「组图」;后台上传多张图片,支持排序和删除。
输出:图片 URL 数组。
{% for img in item.Value %}
<img src="{{ img }}" alt="{{ item.Name }}">
{% endfor %}
适用场景:产品画廊、案例展示、资质证书、活动现场。
注意事项:
- 输出是数组,不能直接当字符串输出。
- 图片顺序以后台排序为准。
- 不建议在一个字段里放几十张图,会影响编辑体验和页面加载。
3.10 文件 file
用于保存附件地址,例如 PDF、说明书、下载包。
设置:字段类型选择「文件」;后台上传附件。
输出:字符串形式的文件 URL。
{% if item.Value %}
<a href="{{ item.Value }}" target="_blank" rel="noopener">下载附件</a>
{% endif %}
适用场景:产品说明书、报价单、合同模板、软件安装包。
注意事项:
- 只保存文件地址,不限制文件类型,请自行控制上传内容。
- 大文件建议使用对象存储,避免占用站点服务器空间。
- 前台下载链接建议加
rel="noopener"。
3.11 文本列表 texts
用于保存一组可重复的结构化条目,例如参数表、团队成员、FAQ、服务项目。
设置:字段类型选择「文本列表」。字段本身的「默认值 / 选项」用于给条目内的单选、多选、下拉提供选项。
每个条目包含:
| 设置项 | 作用 | 取值 / 默认 | 怎么选 / 填写建议 | 影响 / 注意 |
|---|---|---|---|---|
| key | 条目名称,例如「材质」「尺寸」 | — | 填便于识别的名称,与前台展示保持一致 | 名称变更会影响展示与调用,注意同步 |
| type | 条目类型,可为空,空值按单行文本处理 | — | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| value | 单值内容 | — | 简明描述,避免空泛 | 是否展示由模板决定 |
| values | 多值内容,用于多行文本、多选、组图 | — | 简明描述,避免空泛 | 是否展示由模板决定 |
条目支持的 13 种类型:单行文本、数字、多行文本、单选、多选、下拉、单图、组图、文件、日期、时间、日期时间、颜色。条目内不支持富文本、文本列表、关联文档、关联分类和动态时间线。
输出:条目对象数组。
{% for row in item.Value %}
<dt>{{ row.Key }}</dt>
<dd>
{% if row.Type == "images" %}
{% for img in row.Values %}<img src="{{ img }}">{% endfor %}
{% elif row.Type == "checkbox" %}
{{ row.Values|join:", " }}
{% else %}
{{ row.Value }}
{% endif %}
</dd>
{% endfor %}
适用场景:产品参数、团队成员、服务清单、FAQ、规格表。
注意事项:
- 条目内的单选、多选、下拉共用字段配置里的同一组选项,不能给每个条目配置不同选项。
- 日期、时间、日期时间、颜色会按标准格式保存:
2006-01-02、15:04、2006-01-02 15:04:05、#rrggbb。 - 必填只做字段级判断,不要求每个条目都填写。
3.12 关联文档 archive
用于关联一篇或多篇其他文档,例如相关产品、推荐阅读、配套内容。
设置:字段类型选择「关联文档」;在文档编辑页通过文档选择器选择内容。
输出:文档对象数组(包含 Id、Title、Link、Thumb 等字段)。
{% for arc in item.Value %}
<a href="{{ arc.Link }}">{{ arc.Title }}</a>
{% endfor %}
适用场景:相关产品、推荐阅读、配套资料、案例关联。
注意事项:
- 保存的是文档 ID 数组,读取时会转换成文档对象。
- 被关联的文档删除后,该关联会自动失效,不会报错。
- 在文档详情标签和文档参数标签中,默认值可以填一个文档 ID,用于没有选择时的兜底。
3.13 关联分类 category
用于关联一个分类,例如所属行业、所属栏目、所在地区。
设置:字段类型选择「关联分类」;在编辑页通过分类选择器选择一个分类。
输出:分类对象(包含 Id、Title、Link 等字段)。
{% if item.Value %}
<a href="{{ item.Value.Link }}">{{ item.Value.Title }}</a>
{% endif %}
适用场景:所属行业、所属栏目、地区分类、内容归属。
注意事项:
- 保存的是分类 ID,读取时转换成分类对象。
- 分类被删除或隐藏后,输出可能为空,模板中要先判断。
- 只能选择一个分类,多个分类请使用多个字段或关联文档类型。
3.14 日期 date
用于保存日期,例如发布日、活动日期、成立日期。
设置:字段类型选择「日期」;后台使用日期选择器。
输出:字符串,建议统一为 YYYY-MM-DD。
<p>发布日期:{{ item.Value }}</p>
适用场景:成立日期、活动日期、截止日期、生日。
注意事项:
- 保存的是字符串,不是时间戳,不能直接使用
stampToDate。 - 通过不同入口写入时格式可能不同,建议由后台表单或接口统一写入
YYYY-MM-DD。 - 需要精确到时分秒时使用日期时间类型。
3.15 时间 time
用于保存一天中的时刻,例如营业开始时间、每日截单时间。
设置:字段类型选择「时间」;后台使用时间选择器。
输出:字符串,建议统一为 HH:mm 或 HH:mm:ss。
<p>营业时间:{{ item.Value }}</p>
适用场景:营业时间、发货截止时间、预约时段。
注意事项:
- 只表示时刻,不包含日期。
- 保存的是字符串,不做时区转换。
- 跨天营业时间建议拆成开始时间和结束时间两个字段。
3.16 日期时间 datetime
用于保存完整的日期和时间,例如预约时间、发布时间、活动开始时间。
设置:字段类型选择「日期时间」;后台使用日期时间选择器。
输出:字符串,建议统一为 YYYY-MM-DD HH:mm:ss。
<p>预约时间:{{ item.Value }}</p>
适用场景:预约时间、活动开始时间、报名截止时间、服务时间。
注意事项:
- 保存的是字符串,不是 Unix 时间戳。
- 需要按时间排序或比较时,先确认所有入口写入格式一致。
- 需要时间戳时可以在业务侧转换后再写入数字字段。
3.17 颜色 color
用于保存颜色值,例如主题色、色号、标签颜色。
设置:字段类型选择「颜色」;后台使用颜色选择器。
输出:字符串,通常为 #rrggbb。
<span style="color: {{ item.Value }}">彩色文字</span>
适用场景:主题色、产品色号、标签颜色、样式配置。
注意事项:
- 文档字段和用户字段对颜色值不做服务端格式校验,建议由后台选择器写入标准值。
- 文本列表条目内的颜色类型会校验并规范成小写
#rrggbb。 - 不要直接把颜色值拼进不可信的内联样式,避免样式注入。
3.18 动态时间线 timeline
用于保存一条带子项的时间线,例如发展历程、项目进度、物流轨迹、服务流程。
设置:字段类型选择「动态时间线」。该类型只在文档字段和分类字段中可选。
数据结构:
{
"title": "2026 年",
"content": "完成新一轮产品升级",
"status": "已完成",
"images": ["https://www.anqicms.com/uploads/2026/a.jpg"],
"extra": { "负责人": "张三" },
"items": [
{
"title": "**阶段",
"content": "需求调研",
"status": "已完成",
"images": [],
"extra": {},
"items": []
}
]
}
输出:时间线对象。
<h3>{{ item.Value.Title }}</h3>
<p>{{ item.Value.Content }}</p>
<span>{{ item.Value.Status }}</span>
{% for img in item.Value.Images %}
<img src="{{ img }}" alt="{{ item.Value.Title }}">
{% endfor %}
{% for key, val in item.Value.Extra %}
<p>{{ key }}:{{ val }}</p>
{% endfor %}
{% for sub in item.Value.Items %}
<p>{{ sub.Title }} - {{ sub.Status }}</p>
{% endfor %}
适用场景:发展历程、项目里程碑、物流轨迹、服务流程、版本记录。
注意事项:
- 动态时间线以 JSON 保存,不能作为筛选参数。
- 子项结构与顶层结构一致,可以继续嵌套,但前台展示建议控制在两层以内。
- 时间线只适合文档字段和分类字段,其他位置没有该类型。
四、模板调用速查
4.1 不同位置的取值方式
| 设置项 | 作用 | 取值 / 默认 | 怎么选 / 填写建议 | 影响 / 注意 |
|---|---|---|---|---|
| 文档 | {% archiveDetail with name="author" %} |
{% archiveParams params %}...{% endarchiveParams %} |
按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| 分类 | {% categoryDetail with name="industry" %} |
{% categoryDetail extras with name="extra" %} 后循环 extras |
按实际业务范围选择,可多选 | 选择范围决定内容归属与展示 |
| 标签 | {% tagDetail with name="brand_story" %} |
{% tagDetail extras with name="extra" %} 后循环 extras |
按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| 用户 | {% userDetail with name="company" %} |
无统一遍历标签,按字段名逐个读取 | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| 城市分站 | {% placeDetail with name="phone" %} |
{% placeDetail extras with name="extra" %} 后循环 extras |
按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| 留言 | 按 fields 循环 |
{% guestbook fields %}...{% endguestbook %} |
按页面提示与业务需要填写 | 配置以前台实际表现为准 |
| 模板自定义 | {% diy with name="SitePhone" %} |
无遍历标签,按字段名逐个读取 | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
4.2 文档列表中的字段
{% archiveList archives with moduleId=1 showExtra=true limit="10" %}
{% for archive in archives %}
<h3>{{ archive.Title }}</h3>
<p>{{ archive.Extra.author.Value }}</p>
{% endfor %}
{% endarchiveList %}
4.3 默认值判断
除单选、多选、下拉外,未填写时系统会用默认值补位。模板中可以直接判断:
{% if item.Value %}
{{ item.Value }}
{% else %}
未填写
{% endif %}
4.4 接口输出差异
| 设置项 | 作用 | 取值 / 默认 | 怎么选 / 填写建议 | 影响 / 注意 |
|---|---|---|---|---|
/api/archive/detail |
data.extra.{调用字段}.value |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/archive/list |
加 showExtra=1 后为 data[].extra.{调用字段}.value |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/user/detail |
data.extra.{调用字段}.value |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/category/detail |
data.extra.{调用字段} 直接是值 |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/tag/detail |
data.extra.{调用字段} 直接是值 |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/place/detail |
data.extra.{调用字段} 直接是值 |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/order/detail |
data.details[].order_fields 是定义,order_extra 是值 |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
/api/communication/order/detail |
data.order_fields 是定义,order_extra 是值 |
— | 按页面提示与业务需要填写 | 配置以前台实际表现为准 |
五、常见问题与注意事项
5.1 前台不显示字段
按顺序检查:
- 字段是否添加在正确的模型或位置。
- 文档或记录是否真的填写了值;单选、多选、下拉不会自动补默认值。
- 字段是否开启了「跟随文档阅读等级」,当前用户是否已购买或等级足够。
- 文档列表是否加了
showExtra=true。 - 修改模板后是否清理了缓存。
5.2 字段名报错
常见报错:
XXX 已存在:调用字段与系统列或同位置其他字段冲突,不同位置的检查范围略有差异。XXX 命名错误:调用字段没有以小写字母开头,或包含了大写字母、中文、横线等非法字符。
调用字段建议统一使用小写英文加下划线,例如 product_material、company_name。
5.3 修改字段类型后数据异常
文档字段和用户字段的类型与数据库列绑定。后台在字段创建后禁止修改调用字段和类型;如果通过数据库或接口绕过限制,旧数据可能无法按新类型解析。
分类、标签、城市分站、留言、模板内容设置和订单字段使用 JSON 保存,后台可能允许修改类型,但旧值不会自动转换。例如把单行文本改成数字后,原来填写的「约 30 天」会无法按数字解析。
需要改变类型时,建议新增一个字段,迁移完数据后再删除旧字段。
5.4 删除字段
- 文档字段:删除模型表对应列,列数据丢失。
- 用户字段:删除
users表对应列,列数据丢失。 - 其他位置:只删除字段配置,历史 JSON 中的旧值仍在,但不再显示。
删除前请先备份数据库。
5.5 多选值格式不一致
多选字段在不同位置可能输出字符串或数组:
- 文档、用户、留言:英文逗号分隔字符串。
- 分类、标签、城市分站、模板自定义:数组。
模板中请按实际存储位置处理,不要一份模板套所有位置。
5.6 筛选不生效
作为筛选参数 需要同时满足:
- 字段添加在「文档自定义字段」中,而不是分类字段或其他位置。
- 字段类型是单选、多选或下拉。
- 字段没有开启「跟随文档阅读等级」。
- 字段选项中确实配置了可选值。
- 列表页 URL 参数名与调用字段一致。
5.7 图片或文件地址失效
图片和文件字段保存的是附件地址。以下情况会导致地址失效:
- 在附件库中删除了原文件。
- 更换了存储方式但没有迁移文件。
- 修改了站点域名,但模板中使用了硬编码的旧域名。
系统在读取时会按当前存储配置补全地址,但仍建议保留原始附件。
5.8 修改字段后前台没变化
字段配置可能被缓存。保存模型、模板自定义字段或留言设置后,如果前台仍然显示旧内容,请清理站点缓存,再刷新页面。
六、快速选择建议
| 需求 | 推荐类型 |
|---|---|
| 作者、来源、型号 | 单行文本 |
| 年份、数量、库存 | 数字 |
| 地址、备注、说明 | 多行文本 |
| 图文详情 | 富文本 / Markdown |
| 状态、等级、是否 | 单选 |
| 多个标签、适用人群 | 多选 |
| 行业、城市、单位 | 下拉选择 |
| 封面、证书、头像 | 单图 |
| 画廊、案例图 | 组图 |
| PDF、说明书、安装包 | 文件 |
| 参数表、FAQ、团队列表 | 文本列表 |
| 相关产品、推荐阅读 | 关联文档 |
| 所属行业、所属栏目 | 关联分类 |
| 成立日、活动日 | 日期 |
| 营业时间、截单时间 | 时间 |
| 预约时间、报名截止 | 日期时间 |
| 主题色、色号 | 颜色 |
| 发展历程、项目进度 | 动态时间线 |