自定义字段使用教程

📅 2026-11-21 👁️ 0

自定义字段使用教程

自定义字段用于给文档、分类、标签、用户、城市分站、留言、模板设置和订单附加业务字段,而不需要修改程序代码。

安企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 种自定义字段类型

设置项说明

设置项 作用 取值 / 默认 怎么选 / 填写建议 影响 / 注意
参数名称 后台显示的名称 文本,无默认 写便于识别的中文名 —
调用字段 数据库列名与模板调用名 字母开头的英文标识 [源码] 用小写字母、数字、下划线 有数据后不可改名
字段类型 决定输入控件与存储格式 18 种类型 [源码] 按数据形态选,见第三章 创建后不可改类型
默认值 无输入时的初始内容 按类型而定 单选/多选的默认值即选项配置 多选值在文档中是逗号分隔字符串
是否必填 提交时是否强制填写 是 / 否 按业务要求设置 部分位置后台强制为否

常见配置项包括参数名称、调用字段、字段类型、默认值和是否必填;部分位置还支持筛选、跟随阅读等级等选项。逐项说明见「1.1 字段配置项」,支持的类型见「三、18 种字段类型详解」。

操作步骤

  1. 按「二、9 个可配置位置」找到对应后台入口。
  2. 添加字段,填写参数名称、调用字段、字段类型和默认值。
  3. 保存后到对应的内容编辑页填写字段值。
  4. 按「四、模板调用速查」在模板中调用,或通过接口读取。

注意事项

  • 调用字段一旦有数据不要改名,文档字段和用户字段同时是数据库列名。
  • 字段类型变更后旧值不会自动转换,建议新增字段并迁移数据。
  • 模板内容设置的参数名保存时会自动首字母大写,调用时大小写必须一致。
  • 多选值在不同位置的存储格式不同,详见「五、常见问题与注意事项」。

相关文档

一、先理解字段的 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 文档字段

文档字段是最常用的一类,字段会真实添加到内容模型对应的数据表中。

设置步骤:

  1. 进入「内容 → 内容模型」,编辑目标模型。
  2. 在「文档自定义字段」中点击「添加字段」。
  3. 填写参数名称、调用字段、字段类型、默认值和是否必填。
  4. 保存模型后,发布或编辑该模型下的文档,即可在文档表单中看到新字段。

内容模型中的文档自定义字段和分类自定义字段

模板调用:

{# 直接输出单个字段 #}
{% 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 中,不会新增数据库列。

设置步骤:

  1. 进入「内容 → 内容模型」,编辑目标模型。
  2. 在「分类自定义字段」中点击「添加字段」。入口与文档字段在同一个模型设置弹窗中,见上图下半部分。
  3. 保存模型后,编辑该模型下的分类,填写分类字段。

模板调用:

{# 直接读取单个分类字段 #}
{% 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 标签字段

标签字段用于给标签补充介绍、图标、关联内容等信息。

设置步骤:

  1. 进入「内容 → 文档标签」。
  2. 点击页面上的「自定义字段」按钮。
  3. 添加字段并保存。
  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 用户字段

用户字段用于保存会员的公司、职位、行业、资质等扩展资料。

设置步骤:

  1. 进入「功能 → 用户/交易 → 用户管理」。
  2. 点击「设置」,在弹窗中找到「额外字段」。
  3. 添加字段并保存。
  4. 在用户编辑页或注册表单中填写字段值。

用户附加字段设置

模板调用:

{# 读取当前登录用户的扩展字段 #}
{% userDetail with name="company" %}

{# 读取指定用户 #}
<p>公司:{% userDetail with name="company" id=8 %}</p>

注册接口也支持提交用户扩展字段:在 /api/register 的 JSON 中直接使用调用字段作为键,例如 {"user_name": "demo", "company": "示例公司"}。

注意事项:

  • 用户字段会添加到 users 表,属于真实数据库列;删除字段会删除列和数据。
  • 后台保存用户字段时会强制把「是否必填」设为否,必填只在自定义的前台表单中自行校验。
  • 用户字段支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。

2.6 城市分站字段

城市分站字段用于给每个分站补充地址、电话、营业时间、门店图片等信息。

设置步骤:

  1. 进入「内容 → 城市管理」。
  2. 点击「设置」,在「自定义字段」中添加字段。
  3. 编辑具体城市分站时填写字段值。

城市分站的自定义字段设置

模板调用:

{% 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 留言字段

留言字段用于自定义留言表单,例如「公司名称」「预算范围」「需求类型」。

设置步骤:

  1. 进入「功能 → 互动/留言 → 网站留言管理」。
  2. 点击「设置」,在字段列表中维护留言字段。
  3. 前台留言模板通过 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 模板自定义字段(模板内容设置)

模板自定义字段不隶属于某个内容,而是全站共享的键值,适合放客服电话、备案号、公司地址、统一的活动图等。

设置步骤:

  1. 进入「设计 → 模板内容设置」。
  2. 点击添加字段,填写参数名、备注、模块组、字段类型和默认值。参数名保存时首字母会自动大写,建议直接使用 SitePhone 这样的形式。
  3. 模块组用于把字段分成多个标签页,例如「基础信息」「联系方式」。

模板内容设置中的自定义字段

模板调用时名称大小写必须与后台一致:

{# 输出单个字段 #}
{% diy with name="SitePhone" %}

{# 先赋值再使用 #}
{% diy sitePhone with name="SitePhone" %}
<a href="tel:{{ sitePhone }}">{{ sitePhone }}</a>

注意事项:

  • 模板自定义字段必须通过 name 指定调用字段,不能直接遍历。
  • 支持 13 种类型,不支持日期、时间、日期时间、颜色和动态时间线。历史数据中已经存在的颜色等类型字段仍可正常显示和编辑。
  • 修改字段配置后如果前台没有变化,请清理缓存。

2.9 商品定制订单字段

定制商品可以要求买家在下单后补充定制信息,例如刻字内容、尺寸、参考图片。

设置步骤:

  1. 进入「产品」,编辑目标产品。
  2. 打开「定制订单」。
  3. 在「定制订单字段管理」中添加字段并保存。
  4. 买家支付成功后,系统会引导其进入 /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 沟通订单字段

沟通定制订单用于先沟通需求、后报价的场景,字段在全局设置中配置,所有沟通订单共用。

设置步骤:

  1. 进入「订单 → 沟通订单」。
  2. 打开设置,在「自定义订单字段」中添加字段。
  3. 买家创建沟通订单时填写这些字段。

沟通订单的自定义订单字段设置

相关接口:

  • GET /api/communication/fields:获取沟通订单字段定义。
  • POST /api/communication/order/create:创建沟通订单,字段值放在 order_extra 中。
  • GET /api/communication/order/detail:返回 order_fields 和 order_extra。

注意事项:

  • 支持 17 种类型,不支持动态时间线。
  • 字段定义来自全局设置,修改设置后所有沟通订单的表单会一起变化。
  • 必填由前台表单和接口调用方保证,后台保存字段配置时不做强制校验。

三、18 种字段类型详解

后台添加文档字段时,字段类型选择如下图所示:

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 前台不显示字段

按顺序检查:

  1. 字段是否添加在正确的模型或位置。
  2. 文档或记录是否真的填写了值;单选、多选、下拉不会自动补默认值。
  3. 字段是否开启了「跟随文档阅读等级」,当前用户是否已购买或等级足够。
  4. 文档列表是否加了 showExtra=true。
  5. 修改模板后是否清理了缓存。

5.2 字段名报错

常见报错:

  • XXX 已存在:调用字段与系统列或同位置其他字段冲突,不同位置的检查范围略有差异。
  • XXX 命名错误:调用字段没有以小写字母开头,或包含了大写字母、中文、横线等非法字符。

调用字段建议统一使用小写英文加下划线,例如 product_material、company_name。

5.3 修改字段类型后数据异常

文档字段和用户字段的类型与数据库列绑定。后台在字段创建后禁止修改调用字段和类型;如果通过数据库或接口绕过限制,旧数据可能无法按新类型解析。

分类、标签、城市分站、留言、模板内容设置和订单字段使用 JSON 保存,后台可能允许修改类型,但旧值不会自动转换。例如把单行文本改成数字后,原来填写的「约 30 天」会无法按数字解析。

需要改变类型时,建议新增一个字段,迁移完数据后再删除旧字段。

5.4 删除字段

  • 文档字段:删除模型表对应列,列数据丢失。
  • 用户字段:删除 users 表对应列,列数据丢失。
  • 其他位置:只删除字段配置,历史 JSON 中的旧值仍在,但不再显示。

删除前请先备份数据库。

5.5 多选值格式不一致

多选字段在不同位置可能输出字符串或数组:

  • 文档、用户、留言:英文逗号分隔字符串。
  • 分类、标签、城市分站、模板自定义:数组。

模板中请按实际存储位置处理,不要一份模板套所有位置。

5.6 筛选不生效

作为筛选参数 需要同时满足:

  1. 字段添加在「文档自定义字段」中,而不是分类字段或其他位置。
  2. 字段类型是单选、多选或下拉。
  3. 字段没有开启「跟随文档阅读等级」。
  4. 字段选项中确实配置了可选值。
  5. 列表页 URL 参数名与调用字段一致。

5.7 图片或文件地址失效

图片和文件字段保存的是附件地址。以下情况会导致地址失效:

  • 在附件库中删除了原文件。
  • 更换了存储方式但没有迁移文件。
  • 修改了站点域名,但模板中使用了硬编码的旧域名。

系统在读取时会按当前存储配置补全地址,但仍建议保留原始附件。

5.8 修改字段后前台没变化

字段配置可能被缓存。保存模型、模板自定义字段或留言设置后,如果前台仍然显示旧内容,请清理站点缓存,再刷新页面。

六、快速选择建议

需求 推荐类型
作者、来源、型号 单行文本
年份、数量、库存 数字
地址、备注、说明 多行文本
图文详情 富文本 / Markdown
状态、等级、是否 单选
多个标签、适用人群 多选
行业、城市、单位 下拉选择
封面、证书、头像 单图
画廊、案例图 组图
PDF、说明书、安装包 文件
参数表、FAQ、团队列表 文本列表
相关产品、推荐阅读 关联文档
所属行业、所属栏目 关联分类
成立日、活动日 日期
营业时间、截单时间 时间
预约时间、报名截止 日期时间
主题色、色号 颜色
发展历程、项目进度 动态时间线

相关文章

文档分类

文档分类用于按模型组织文档,维护分类层级、模板、显示状态和分类自定义字段。

2026-11-21

图片资源管理

图片资源管理用于上传、分类、检索和维护网站所有图片与视频资源。

2026-11-21

内容模型使用帮助

内容模型决定了整站的文档功能。系统默认内置了 文章模型 和 产品模型 这2个模型。系统内置的内容模型可以修改,但不能删除。新增的自定义模型可以修改和删除。需要注意的是,当你想删除模型的时候,一定要深思熟虑,删除模型后,该模型下的所有文档和分类也会一并被删除。内容模型可以修改的内容字段有:模型名称模型

2022-06-20

文档标签使用帮助

文档标签管理可以查看和管理所有的文档标签。文档标签不分分类和模型,同一个标签可以同时给不同的内容模型的文档标记。文档标签比较简单,它有标签名称、索引字母、描述内容等。你可以在标签管理中进行新增、编辑、删除等操作。新增文档标签中,可以填写和添加的字段有:标签名称标签的显示名称。索引字母索引字母只会包含

2022-06-20

文档列表

文档列表是全站文档的管理中心,用于筛选、查找、编辑、批量处理文档,以及进入回收站和批量导入。

2026-11-21

内容模型

内容模型定义文档的类型、表名、标题名称和自定义字段,是文档、分类字段的配置入口。

2026-11-21

单页面管理

单页面管理用于创建「公司介绍」「联系我们」等独立页面,维护名称、SEO 信息、URL 别名和内容。

2026-11-21

城市管理

城市管理用于开启城市分站、配置分站形式,并维护城市分站及其自定义字段。

2026-11-21