在AnQiCMS中，我们常常需要根据网站的实际需求，创建各种各样的内容。AnQiCMS强大的自定义内容模型功能，正是为了满足这种灵活性而设计的。它允许我们为不同类型的内容（如文章、产品、案例等）定义专属的字段，从而更精确地管理和展示信息。那么，这些自定义的字段数据，我们又该如何在网站的前台页面上进行精确地调用和显示呢？

这个过程通常分为两大部分：首先是理解后台自定义字段的设置，其次是掌握前端模板的调用方法。

第一步：理解自定义内容模型与字段的定义

在AnQiCMS的后台，所有自定义内容模型的管理都集中在“内容管理”下的“内容模型”模块。当我们创建一个新的内容模型或者编辑现有模型时，可以为该模型添加“自定义字段”。

每个自定义字段在定义时，有几个关键的属性需要我们关注：

  • 参数名： 这是后台界面上显示给编辑人员看的友好名称，比如“产品特点”、“作者简介”等。
  • 调用字段： 这是最重要的一个属性。它是我们在前端模板中用来引用这个自定义字段的唯一标识符，通常建议使用英文小写字母，因为它将作为代码中的变量名。例如，为“产品特点”定义的调用字段可能是productFeatures，为“作者简介”定义的调用字段可能是authorBio。
  • 字段类型： AnQiCMS支持多种字段类型，如单行文本、数字、多行文本、单项选择、多项选择、下拉选择等。不同的字段类型，决定了数据在后台的录入形式，也间接影响前端的显示方式。
  • 默认值： 如果字段有默认值，当内容编辑者未填写时，系统会自动使用这里设定的默认值。

理解了这些定义，我们就为在前台页面精准显示数据打下了基础。前端模板将主要通过“调用字段”来获取对应的数据。

第二步：在前台模板中调用自定义字段数据

AnQiCMS的模板系统采用了类似Django模板引擎的语法，使用双花括号{{变量}}来输出变量，使用单花括号和百分号{% 标签 %}来调用功能标签。

1. 在内容详情页（archiveDetail标签）显示自定义字段

在浏览具体内容的详情页面（例如{模型table}/detail.html或{模型table}/{文档id}.html这类模板）时，我们通常会使用archiveDetail标签来获取当前文档的详细数据。

直接按调用字段名获取单个自定义字段： 如果自定义字段是单一的文本、数字或简单的选择项，并且我们知道其精确的“调用字段”名称，可以直接通过archiveDetail标签，并指定name参数为该字段的“调用字段”来获取。

例如，假设我们为“文章”模型定义了一个调用字段为source（文章来源）的自定义字段，在文章详情页中，可以这样显示它：

<div>文章来源：{% archiveDetail with name="source" %}</div>

或者，将其赋值给一个变量再输出：

{% archiveDetail articleSource with name="source" %}
<div>文章来源：{{ articleSource }}</div>

遍历所有自定义字段（archiveParams标签）： 当一个内容模型自定义了多个字段，或者我们希望以更通用的方式遍历并显示所有自定义字段时，archiveParams标签就显得非常方便了。它能够获取当前文档所有自定义的参数。

archiveParams标签可以有两种主要的用法：

  • 以数组形式遍历（推荐）： 默认情况下，或指定sorted=true时，archiveParams会返回一个包含所有自定义字段的数组。数组中的每个元素又是一个对象，通常包含Name（参数名）和Value（字段数据）两个属性。这非常适合用for循环来显示。

    {% archiveParams params %}
<div>
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
</div>

    这段代码会列出后台为当前内容定义的所有自定义字段的“参数名”及其“值”。

  • 以Map（键值对）形式直接访问（了解）： 如果指定sorted=false，archiveParams会返回一个Map对象，我们可以直接通过params.调用字段名.Value来访问特定字段的值。这种方式在需要精确访问某个自定义字段，但又不方便直接使用archiveDetail with name="字段"时，可以作为补充。

    {% archiveParams params with sorted=false %}
    <div>作者简介：{{params.authorBio.Value}}</div>
    <div>产品特点：{{params.productFeatures.Value}}</div>
{% endarchiveParams %}

处理富文本或Markdown类型的自定义字段： 如果自定义字段的类型是多行文本，并且在后台开启了Markdown编辑器，或者内容本身就是HTML富文本，那么在前端显示时，为了确保HTML标签能被浏览器正确解析，我们需要使用safe过滤器。同时，如果内容是Markdown格式，我们可能还需要使用render=true参数来确保Markdown被正确转换为HTML。

{% archiveDetail richTextContent with name="rich_content" render=true %}
<div>详细描述：{{ richTextContent|safe }}</div>

2. 在内容列表页（archiveList标签）显示自定义字段

在列表页面（例如文章列表页或产品列表页），我们需要遍历多个内容项。archiveList标签会返回一个内容的集合，我们在for循环中获取每个item（即每条内容）的数据。

要显示列表中每个内容的自定义字段，我们不能直接在archiveList的for循环外部调用archiveParams，而需要在for循环内部，针对当前的item再次使用archiveParams标签，并通过id参数传入当前循环项的Id。

例如，在一个文章列表中显示每篇文章的“作者”自定义字段：

”`twig {% archiveList archives with type=“page” limit=“10” %}

{% for item in archives %}
<article>
    <h2><a href="{{item.Link}}">{{item.Title}}</a></h2>
    <div>
        {# 在这里获取当前文章的自定义字段 #}
        {% archiveParams articleCustomFields with id=item.Id %}
            {% for field in articleCustomFields %}
                {% if field.Name == "作者" %} {# 假设自定义字段的参数名为“作者” #}
                    <span>作者：{{field.Value}}</span>
                {% endif %}
            {% endfor %}
        {% endarchiveParams %}
        <span>发布日期：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>