在AnQiCMS中，如何确保内容模型自定义字段正确地显示在前台页面？

在AnQiCMS中，我们常常会遇到需要展示各种个性化内容的情况。内置的文章、产品模型虽然功能强大，但有时仍然无法满足特定的业务需求。这时候，内容模型中的自定义字段就成了我们的得力助手，它们让网站内容管理变得更加灵活。但自定义字段设置好了，如何确保它们能正确地呈现在网站前台，让访客看到呢？今天，我们就来深入探讨这个问题。

内容模型自定义字段的创建与管理

首先，让我们回顾一下如何在后台创建这些自定义字段。在AnQiCMS后台，导航到“内容管理”下的“内容模型”，您会看到系统内置的“文章模型”和“产品模型”。我们可以在这里编辑现有模型，或者创建全新的自定义模型。

无论是编辑还是新增模型，核心都是在“内容模型自定义字段”区域添加新的字段。每添加一个字段，都需要填写几个关键信息：

  • 参数名： 这是后台显示给您看的中文名称，方便您理解这个字段的用途，比如“文章作者”、“产品尺寸”。
  • 调用字段： 这是最关键的一项。 它是一个英文小写字母组成的名称，例如 author、product_size、images_gallery。这个名称是模板中用来识别和调用该字段数据的唯一标识，务必确保其准确性，且建议使用有意义的英文名称，避免与系统内置字段名冲突。
  • 字段类型： AnQiCMS支持多种字段类型，如单行文本、数字、多行文本、单项选择、多项选择和下拉选择。选择合适的字段类型，能确保您在后台填写内容时有正确的输入方式。
  • 是否必填： 根据需求设置该字段是否为必填项。
  • 默认值： 如果该字段需要有预设值，可以在这里填写。对于选择类型的字段，这里用来设置可供选择的选项。

完成这些设置并保存后，自定义字段就成功添加到内容模型中了。

在文档或分类中填写自定义字段

当您在后台创建或编辑具体的文档（文章、产品等）时，这些自定义字段就会出现在编辑界面。例如，在“添加文档”页面，您会在“其他参数”的折叠框内看到这些自定义字段。根据之前定义的字段类型，您可以在这里填入相应的内容，比如文章的“作者”、产品的“材质”等。如果某个字段设置了默认值，而您没有手动填写，那么前台在调用时就会显示这个默认值。

同样，如果您为某个分类模型自定义了字段（例如分类的Banner图），这些字段也会在“文档分类”的编辑页面中出现，供您为分类填写专属信息。

将自定义字段呈现在前台页面

现在，我们来到了最核心的部分——如何让这些自定义字段在前台页面上“露面”。AnQiCMS的模板系统采用了类似Django模板引擎的语法，使用双花括号 {{变量}} 来输出变量，使用 {% 标签 %} 来实现逻辑控制和数据调用。

1. 调用单个自定义字段

如果您只想显示某个特定的自定义字段值，可以直接使用文档详情（archiveDetail）、分类详情（categoryDetail）或单页详情（pageDetail）标签，配合 name 参数来指定字段的“调用字段”名称。

例如，您为“文章模型”添加了一个“调用字段”为 author 的自定义字段，并希望在文章详情页显示作者名，可以这样写：

<p>文章作者：{% archiveDetail with name="author" %}</p>

如果您的自定义字段是“产品模型”下的 material，可以在产品详情页这样调用：

<p>产品材质：{% archiveDetail with name="material" %}</p>

对于分类自定义字段，例如在分类编辑时添加了一个“调用字段”为 category_slogan 的字段，在分类列表或详情页可以这样调用：

<p>分类口号：{% categoryDetail with name="category_slogan" %}</p>

请记住，name 参数的值必须与您在后台“内容模型”中设置的“调用字段”名称完全一致，包括大小写。

2. 循环展示所有自定义字段（针对文档）

有时，一个模型可能有多个自定义字段，您可能希望将它们全部列出，而无需逐一编写标签。AnQiCMS提供了 archiveParams 标签，专门用于循环展示文档的自定义字段。

<div class="custom-fields">
    {% archiveParams params %}
    {% for item in params %}
    <p>
        <span>{{item.Name}}：</span> <!-- 显示后台设置的“参数名”（中文名） -->
        <span>{{item.Value}}</span> <!-- 显示该字段的值 -->
    </p>
    {% endfor %}
    {% endarchiveParams %}
</div>

这里，params 是您自定义的变量名，它会包含一个数组，每个元素代表一个自定义字段。item.Name 会输出您在后台设置的中文“参数名”，而 item.Value 则会输出该字段的具体内容。

如果您想排除某些不需要显示的字段，可以在循环中增加条件判断：

<div class="custom-fields">
    {% archiveParams params %}
    {% for item in params %}
    {% if item.FieldName != '不想显示的字段调用名' %}
    <p>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </p>
    {% endif %}
    {% endfor %}
    {% endarchiveParams %}
</div>

3. 处理特殊字段类型

  • 图片字段： 如果您的自定义字段是图片类型（无论是单图还是组图），例如“调用字段”为 product_images，您可能需要遍历图片地址并用 <img> 标签显示：

    {% archiveDetail productImages with name="product_images" %}
<div class="product-gallery">
    {% for imgUrl in productImages %}
    <img src="{{imgUrl}}" alt="产品图片" />
    {% endfor %}
</div>

    对于系统内置的缩略图、多图等字段，如 Logo (首图)、Images (组图)，可以直接通过 archiveDetail with name="Logo" 或 archiveDetail archiveImages with name="Images" 调用，Images 字段通常也需要循环来显示。

  • 富文本/Markdown字段： 如果自定义字段是多行文本，并且您在后台使用了富文本编辑器或Markdown编辑器，输出时需要特别注意。为了让浏览器正确解析其中的HTML或Markdown内容，您需要使用 |safe 过滤器。如果启用了Markdown编辑器，还可以使用 |render 过滤器先将Markdown转换为HTML：

    <div class="introduction-content">
    {% archiveDetail introContent with name="introduction" %}
    {{ introContent|render|safe }}
</div>

    |safe 告诉模板引擎这段内容是安全的HTML，不需要转义；|render 则是将Markdown文本转换为HTML。

  • 选择类型字段（单选、多选、下拉）： 这些字段的值会直接显示为选中的选项。如果是多选类型，item.Value 可能是一个包含多个选项的字符串，您可能需要进行额外的处理，或者在模板中按需求进行显示。

常见注意事项

  1. “调用字段”的准确性： 务必确保模板中 name 参数的值与后台“内容模型”中设置的“调用字段”名称完全一致，包括大小写。这是数据能否正确显示的根本。
  2. 模板缓存： 修改模板文件后，有时浏览器可能会有缓存。如果前台没有立即生效，可以尝试清理浏览器缓存，或者在AnQiCMS后台点击“更新缓存”按钮。