内容模型自定义字段如何在前端模板中进行灵活调用和显示？

在使用安企CMS管理网站内容时，其强大的内容模型和自定义字段功能为网站的个性化需求提供了极大的灵活性。很多时候，我们不仅需要发布常规的文章标题、内容等，还需要针对特定类型的文章或产品，添加一些独有的信息，比如文章的作者、产品型号、上市日期、特殊卖点等。这些信息正是通过内容模型自定义字段来实现的。那么，如何在网站前端模板中灵活地调用和展示这些自定义字段呢？这正是我们今天要深入探讨的问题。

理解内容模型与自定义字段

首先，我们来简要回顾一下安企CMS中内容模型和自定义字段的概念。内容模型，顾名思义，就像是为不同类型内容量身定制的“骨架”或“模板”。例如，你可以创建一个“文章模型”用于博客文章，一个“产品模型”用于商品信息展示。每个模型都包含一系列标准字段（如标题、内容、分类等），同时，安企CMS允许我们为每个模型添加“自定义字段”。

自定义字段的类型非常丰富，包括单行文本（用于短文本输入，如作者名）、数字（用于价格、库存等）、多行文本（用于长段描述）、单项选择、多项选择和下拉选择（用于预设选项的选取）。在后台，我们可以轻松地为某个内容模型配置这些自定义字段，设置它们的名称、调用字段名、类型、是否必填以及默认值。这些设置完成后，当我们在该模型下发布内容时，就能看到对应的自定义字段输入框，方便地录入各种个性化数据。

前端模板调用的基础

安企CMS的前端模板系统基于Django模板引擎语法，这意味着它拥有强大且直观的变量和标签调用机制。在模板文件中，我们使用双花括号 {{变量}} 来输出变量的值，而使用单花括号和百分号 {% 标签 %} 来执行逻辑控制或调用特定功能。自定义字段的值，本质上也是内容数据的一部分，同样遵循这套调用规则。

所有的模板文件都存放在 /template 目录下，静态资源（CSS、JS、图片）则在 /public/static/。变量名通常采用驼峰命名法（例如 archive.Title），方便理解和使用。

灵活调用自定义字段的核心标签

在安企CMS中，调用内容模型自定义字段主要依赖于两个核心标签：archiveDetail 和 archiveParams。

1. 使用 archiveDetail 标签调用特定自定义字段

当你知道自定义字段的“调用字段”名称时，archiveDetail 标签是直接、高效的调用方式。这个标签主要用于在文档详情页获取当前文档或指定文档的详细数据。

调用方法： {% archiveDetail 变量名称 with name="自定义字段的调用字段名" %}

其中，变量名称 可以省略，如果省略，标签会直接输出该字段的值。如果指定了 变量名称，则可以将获取到的值赋给这个变量，后续在模板中通过 {{变量名称}} 来使用。

示例场景： 假设我们为“文章模型”添加了一个名为“作者（调用字段：author）”的单行文本字段，并在“产品模型”中添加了一个名为“产品批次号（调用字段：batch_number）”的单行文本字段。

• 在文章详情页调用作者：

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

  或者将值赋给变量再使用：

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

• 在产品详情页调用产品批次号：

  <p>产品批次号：{% archiveDetail with name="batch_number" %}</p>
  

处理特殊字段类型：

• 组图字段（例如名为 product_images 的组图自定义字段）： 组图字段通常会返回一个图片URL的数组。这时，你需要通过循环来展示所有图片：

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

• 富文本字段（例如名为 full_description 的多行文本字段，使用Markdown或富文本编辑器）： 如果自定义字段存储的是HTML内容或Markdown内容，直接输出可能会显示原始标签。这时，需要使用 safe 过滤器或 render 过滤器来解析HTML或渲染Markdown：

  <div class="full-description">
      {% archiveDetail productDescription with name="full_description" %}
      {{ productDescription|safe }}  {# 如果是HTML内容 #}
      {# 或者 {{ productDescription|render|safe }} 如果是Markdown内容 #}
  </div>
  

  render 过滤器会将Markdown内容转换为HTML，safe 过滤器则确保HTML内容不被转义而直接显示。

2. 使用 archiveParams 标签循环遍历所有自定义字段

当你不确定有哪些自定义字段，或者需要以统一的方式展示所有自定义字段及其值时，archiveParams 标签就显得非常有用。它能够获取当前文档或指定文档的所有自定义参数。

调用方法： {% archiveParams 变量名称 with id="文档ID" sorted=true %}

• 变量名称：用于接收所有自定义字段的数组或Map对象。
• id：可选参数，用于指定获取哪个文档的自定义字段。如果省略，默认获取当前页面的文档。
• sorted：可选参数，默认为 true。
  • sorted=true（默认）：变量名称 将是一个有序的数组，每个元素包含 Name（参数名，即中文名称）和 Value（参数值）。这种方式适合通过 for 循环遍历显示。
  • sorted=false：变量名称 将是一个无序的Map对象，你可以通过 变量名称.调用字段名.Name 和 变量名称.调用字段名.Value 直接访问特定字段。

示例场景： 我们希望在产品详情页展示所有的产品参数，而这些参数可能在后台会动态增加或修改。

• 以有序数组形式遍历显示所有自定义字段：

  <div class="product-parameters">
      <h3>产品参数</h3>
      <ul>
          {% archiveParams params %} {# 默认 sorted=true #}
          {% for item in params %}
              <li>
                  <span>{{ item.Name }}：</span>
                  <span>{{ item.Value }}</span>
              </li>
          {% endfor %}
          {% endarchiveParams %}
      </ul>
  </div>
  

  这种方式非常适合通用性的参数展示，无需知道每个字段的具体调用字段名。

• 以无序Map形式直接访问特定自定义字段： 假设我们有 material (材质) 和 weight (重量) 两个自定义字段。

  <div class="product-specs">
      {% archiveParams productSpecs with sorted=false %}
      <p>材质：{{ productSpecs.material.Value }}</p>
      <p>重量：{{ productSpecs.weight.Value }}</p>
      {% endarchiveParams %}
  </div>
  

  这种方式的优势在于可以直接通过自定义字段的调用字段名来精确获取，但需要确保自定义字段的调用字段名是已知的且稳定的。

结合实际的页面构建

在实际构建网站时，自定义字段的灵活调用能够大大提升内容展示的丰富度。例如，一个电商网站的产品页面，可以利用自定义字段展示产品的各种属性：颜色、尺寸、材质、库存、产地等。一个内容网站的文章页面，可以展示文章的原创性声明、引用来源、所属专栏等。

常用步骤：

1. 确定内容类型： 需要哪些不同类型的内容，如新闻、产品、案例等。
2. 创建/编辑内容模型： 在安企CMS后台创建或编辑相应的内容模型。
3. 添加自定义字段： 根据内容类型的需求，为模型添加必要的自定义字段，并仔细定义“调用字段”名称和字段类型。
4. 设计前端模板： 在 template 目录下的对应模板文件（例如文章详情页 archive/detail.html）中，使用 archiveDetail 或 archiveParams 标签来调用和展示这些自定义字段。
5. 内容发布： 在后台发布内容时，为自定义字段填写数据。

通过以上步骤，我们就能充分利用安企CMS的自定义字段功能，构建出高度定制化且富有表现力的网站内容。

常见问题 (FAQ)

1. 为什么我在 archiveList 循环中无法直接通过 item.我的自定义字段 调用？ archiveList 标签主要用于获取文档列表的常用基础字段，例如标题、链接、描述等。为了保持列表查询的效率和数据精简，它默认不会把所有自定义字段都包含在 item 对象中。如果你需要在列表页中展示自定义字段，推荐的做法是在 archiveList 循环内部，针对每个 item，使用 archiveDetail 标签（通过 id=item.Id 参数指定当前文档）或 archiveParams 标签来获取并显示其自定义字段。不过，如果自定义字段的值在列表页只作为筛选条件或简单提示，也可以考虑将该字段通过后台设置，在archiveList的查询参数中明确指定，但通常这种方式会增加数据库查询的复杂度。

2. 我有一个自定义字段是多选框，在前端怎么显示所有选中的值？ 多选框类型的自定义字段通常会在后端存储为包含多个值的字符串（例如 值1,值2,值3）或数组。在前端模板中，你可以使用 split 过滤器将这个字符串按分隔符（通常是逗号 ,）切割成数组，然后通过 for 循环遍历这个数组来显示所有选中的值。 例如：

   {% archiveDetail selectedOptions with name="my_multi_select_field" %}
   <ul>
   {% for option in selectedOptions|split:"," %}
       <li>{{ option }}</li>
   {% endfor %}
   </ul>
   

3. 我自定义了一个富文本编辑器字段，为什么直接显示出来是带 HTML 标签的文本？ 富文本编辑器存储的内容通常是带有