如何在AnQiCMS前端展示内容模型中定义的自定义字段？

AnQiCMS 的灵活内容模型是其核心优势之一，它让我们可以根据实际业务需求，为不同类型的内容定义独特的字段，从而摆脱传统 CMS 固定的内容结构限制。当我们创建好这些自定义字段后，接下来的关键一步就是在网站前端将它们优雅地展示出来。

这篇文章将详细为您介绍如何在 AnQiCMS 后台定义自定义字段，以及如何在前端模板中灵活地调用和展示这些信息，让您的网站内容更具个性化和实用性。

一、在后台内容模型中定义自定义字段

在 AnQiCMS 中，所有的内容发布都基于“内容模型”。无论是文章、产品还是其他自定义类型，都对应一个特定的内容模型。要展示自定义字段，我们首先需要在对应的内容模型中添加这些字段。

  1. 进入内容模型管理 登录 AnQiCMS 后台，导航到“内容管理”菜单，然后点击“内容模型”子菜单。您会看到系统内置的“文章模型”和“产品模型”，也可以创建新的自定义模型。选择您想要添加自定义字段的模型，点击“编辑”按钮进入。

  2. 添加自定义字段 在模型编辑界面，您会找到“内容模型自定义字段”区域。这里就是我们定义个性化字段的地方。点击“添加字段”，会出现一个新的表单行，您需要填写以下信息：

    • 参数名 (Name)：这是字段在后台管理界面和编辑页面显示的中文名称，方便您理解和管理，例如“文章来源”、“产品型号”、“发布日期”等。
    • 调用字段 (FieldName)：这是前端模板中用来调用该字段的唯一标识符，必须是英文小写字母。例如，如果参数名是“文章来源”，您可以将其调用字段设置为 source；如果参数名是“产品型号”，可以设置为 model_number。请记住这个“调用字段”，它是前端展示的关键。
    • 字段类型 (Type)：选择适合您内容类型的字段，例如：
      • 单行文本：适用于简短的文字内容，如作者、短标题。
      • 数字：只允许输入数字。
      • 多行文本：适用于较长的文字描述。
      • 单项选择、多项选择、下拉选择：提供预设选项供选择，选项内容在“默认值”中设置，一行一个选项。
    • 是否必填 (Required)：决定该字段在发布内容时是否必须填写。
    • 默认值 (Content)：为字段设置一个初始值或提供选项（对于选择类型字段）。

    举个例子，假设我们想为“文章模型”添加一个“作者邮箱”字段，方便读者直接联系。我们可以这样设置：

    • 参数名：作者邮箱
    • 调用字段：author_email
    • 字段类型：单行文本
    • 是否必填：否
    • 默认值：空

    完成字段添加后，记得点击保存，使改动生效。

二、在前端模板中展示自定义字段

自定义字段定义好并发布了内容之后，我们就可以在网站的前端模板中将它们展示出来。AnQiCMS 采用类似 Django 的模板引擎语法，通过特定的标签来调用数据。通常，自定义字段的展示会集中在文档的详情页模板（如 article/detail.html 或 product/detail.html）中。

在模板文件中，您可以选择两种主要的方式来展示自定义字段：直接调用特定字段或循环遍历所有自定义字段。

  1. 直接调用特定自定义字段 如果您知道要展示哪个自定义字段，并且它是一个独立的、不需要循环处理的值（如文本、数字），那么可以直接使用 archiveDetail 标签来获取它的值。

    假设您在后台定义了一个“文章来源”字段，其“调用字段”为 source，那么在文章详情页模板中，您可以这样直接调用并显示它：

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

    如果您的自定义字段名为 author_email，同样可以这样调用：

    <p>联系作者：<a href="mailto:{% archiveDetail with name="author_email" %}">{% archiveDetail with name="author_email" %}</a></p>

    这种方式简洁明了，适用于需要精确控制某个特定字段展示位置和格式的场景。

  2. 循环遍历所有自定义字段 如果您希望在文档详情页展示所有自定义字段（或者不确定具体有哪些字段，但想统一展示），可以使用 archiveParams 标签。这个标签会返回一个包含所有自定义字段的数组或映射（map），您可以遍历它来动态展示。

    archiveParams 标签默认会返回一个排序后的数组，每个元素包含 Name（参数名，即后台设置的中文名）和 Value（字段值）。

    <div>
    <h3>其他参数</h3>
    {% archiveParams params %}
        {% for item in params %}
            <p>{{item.Name}}：{{item.Value}}</p>
        {% endfor %}
    {% endarchiveParams %}
</div>

    这段代码会遍历当前文档所有已定义的自定义字段，并以“参数名：字段值”的形式逐一显示。

    如果您想以映射（map）形式获取数据以便通过键名直接访问，可以添加 sorted=false 参数：

    {% archiveParams params with sorted=false %}
    <div>作者邮箱：{{params.author_email.Value}}</div>
{% endarchiveParams %}

    但通常情况下，直接使用 {% archiveDetail with name="调用字段" %} 方式会更直观方便。

  3. 处理特殊字段类型（例如图片组、多选） 有些自定义字段类型可能需要特别处理才能更好地在前台展示。

    • 图片组字段： 如果您定义了一个自定义字段用于上传多张图片（例如“产品相册”，调用字段为 product_gallery），archiveDetail 标签会返回一个图片 URL 的数组。您需要循环遍历这个数组来展示图片：

      <h3>产品相册</h3>
<ul class="product-gallery">
    {% archiveDetail images_list with name="product_gallery" %}
    {% if images_list %}
        {% for img_url in images_list %}
            <li><img src="{{ img_url }}" alt="产品图片" loading="lazy"></li>
        {% endfor %}
    {% endif %}
</ul>

    • 多项选择字段： 如果您的自定义字段是“多项选择”（例如“适用场景”，调用字段为 applicable_scenes），后台保存时通常是逗号分隔的字符串（例如“家庭,办公,旅行”）。在前端展示时，您可以使用 |split 过滤器将其转换成数组，然后循环显示：

      <p>适用场景：
    {% archiveDetail scene_str with name="applicable_scenes" %}
    {% if scene_str %}
        {% for scene in scene_str|split:"," %}
            <span>{{ scene }}</span>{% if not forloop.Last %},{% endif %}
        {% endfor %}
    {% else %}
        <span>暂无</span>
    {% endif %}
</p>

    • 富文本编辑器字段： 如果您的自定义字段使用了富文本编辑器（如“产品详情补充”，调用字段为 extra_details），其内容会包含 HTML 标签。为了确保这些 HTML 内容能够被浏览器正确解析而不是作为纯文本显示，您需要使用 |safe 过滤器。

      <h3>详情补充</h3>
<div>
    {% archiveDetail extra_content with name="extra_details" %}
    {{ extra_content|safe }}
</div>

      这样，字段中定义的图片、排版等 HTML 格式就能原样显示了。

总结

通过灵活运用 AnQiCMS 的内容模型和前端模板标签，您可以轻松地将任何自定义字段展示在网站上，满足各种个性化的内容展示需求。无论是简单的文本、数字，还是复杂的图片组、多选框，AnQiCMS