安企CMS如何调用自定义的文档字段（如作者、价格）并展示？

安企CMS以其卓越的灵活性和可定制性，为广大网站运营者提供了强大的内容管理能力。在日常的网站运营中，我们常常会遇到标准字段（如标题、内容、发布时间）无法完全满足特定内容展示需求的情况。此时，自定义文档字段便成了我们的得力助手，例如为一篇文章添加“作者”信息，或者为一件商品补充“价格”属性等。那么，在安企CMS中，我们如何才能灵活地调用这些自定义字段并将其展示在网站页面上呢？

今天，作为资深的网站运营专家，我将带您深入了解安企CMS中自定义文档字段的定义、调用与展示策略，确保您能将技术细节转化为易于理解的实用操作。

一、为何需要自定义文档字段？

安企CMS的核心优势之一就是其“灵活的内容模型”设计。在许多内容管理系统中，内容的字段是固定的，这在很大程度上限制了内容的表现形式和业务的扩展性。例如，一个简单的博客文章可能只需要标题、内容和发布日期，但如果你要发布产品信息，你可能还需要价格、库存、SKU、品牌等一系列专属字段。如果这些信息都挤在“内容”字段里，不仅管理起来一团糟，前端展示时也难以结构化和美观。

自定义文档字段的出现，正是为了打破这种限制。它允许你根据实际业务需求，为不同的内容模型（如“文章模型”、“产品模型”等）添加独有的、个性化的数据字段。这样，每种类型的内容都能拥有最贴合自身特性的数据结构，极大地提升了内容管理的精细度和前端展示的灵活性。

二、在安企CMS后台定义自定义字段

要调用和展示自定义字段，首先我们需要在后台正确地定义它们。这个过程其实非常直观：

  1. 进入内容模型管理： 登录安企CMS后台，导航至“内容管理”菜单，选择“内容模型”。这里列出了系统中所有已有的内容模型，例如默认的“文章模型”和“产品模型”。
  2. 选择或创建模型： 你可以选择一个现有模型进行编辑，或者根据需要创建一个全新的内容模型。
  3. 添加自定义字段： 进入模型编辑页面后，你会看到一个名为“内容模型自定义字段”的区域。点击“添加字段”，便可以开始定义你的专属字段了。
    • 参数名： 这是这个字段在后台界面上显示给管理员看的名称，比如“文章作者”、“商品价格”。
    • 调用字段： 这是最关键的部分！它是一个英文字符串，是你在前端模板中调用此字段时所使用的“键名”。务必使用小写英文字母，且保持唯一性，例如author、price。这个“调用字段”就是我们稍后在模板中引用的“秘密武器”。
    • 字段类型： 根据你的数据特性选择合适的类型，如“单行文本”（用于作者姓名）、“数字”（用于价格、库存）、“多行文本”（用于商品详情的简要描述）、“单项选择”、“多项选择”或“下拉选择”等。
    • 是否必填 & 默认值： 根据业务逻辑设置。如果设定了默认值，当你在编辑文档时未填写此字段，前端将自动显示预设的默认值。

完成字段定义后，保存模型。现在，当你去“内容管理”下添加或编辑该模型下的文档时，你就会在“其他参数”区域看到你新定义的自定义字段，可以为每篇文档录入相应的数据了。

三、在模板中调用自定义字段并展示

定义好字段并录入数据后，接下来的核心步骤就是在前端模板中将其展示出来。安企CMS的模板引擎（类似Django语法）提供了强大的标签来帮助我们实现这一点。

1. 调用单个特定字段

当你在文档详情页（例如，显示某篇博客文章的完整内容）时，你可能需要显示该文章的特定自定义字段，比如作者。

  • 使用archiveDetail标签： 对于文档详情页，最直接的方法是使用archiveDetail标签配合name参数。name参数的值正是你在后台定义的“调用字段”。

    {# 假设你定义了一个“调用字段”为 author 的自定义字段 #}
<div>文章作者：{% archiveDetail with name="author" %}</div>


{# 假设你定义了一个“调用字段”为 price 的自定义字段 #}
<div>商品价格：￥{% archiveDetail with name="price" %}</div>

    这里的archiveDetail标签会智能地获取当前页面的文档信息。如果你想指定获取某个ID的文档字段，也可以通过id参数实现，例如{% archiveDetail with name="author" id="10" %}。

  • 在文档列表循环中调用： 如果你是在archiveList标签的循环中（比如显示一个文章列表），想要展示列表项的自定义字段，可以直接通过循环变量的属性来访问：

    {% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
    <li>
        <a href="{{item.Link}}">
            <h5>{{item.Title}}</h5>
            {# 直接访问 item 对象的自定义字段 #}
            <p>作者：{{item.author}}</p>
            <p>价格：￥{{item.price}}</p>
        </a>
    </li>
    {% endfor %}
{% endarchiveList %}

    在这个例子中，item代表了循环中的当前文档对象，你可以直接使用item.调用字段名称的方式来获取其自定义字段的值。这种方式非常适合在列表页简要展示每项内容的自定义信息。

2. 遍历所有自定义字段

有时候，你可能想在一个区块内展示某篇文档的所有自定义字段，比如一个产品详情页面的“产品参数”区域。这时，archiveParams标签就派上了用场，它能帮助你遍历并显示一个文档的所有附加参数。

  • 使用archiveParams标签： 这个标签会获取当前文档（或指定ID的文档）的所有自定义字段，并将它们组织成一个可循环的列表。

    <div class="product-parameters">
    <h3>产品参数</h3>
    {% archiveParams params %}
        {% for item in params %}
        <p>
            <span>{{item.Name}}：</span> {# item.Name 是你在后台定义的“参数名” #}
            <span>{{item.Value}}</span> {# item.Value 是该字段的具体值 #}
        </p>
        {% endfor %}
    {% endarchiveParams %}
</div>

    这里，params是一个包含所有自定义字段的对象集合，每个item都包含Name（字段显示名称）和Value（字段值）。archiveParams标签还支持sorted=true（默认值，按后台排序）和sorted=false（无序Map对象，可按params.调用字段.Value直接取值）两种模式，以适应不同场景的需求。

3. 结合不同字段类型与特殊处理

对于不同类型的自定义字段，前端展示时可能需要一些额外处理：

  • 多行文本（富文本）： 如果你的自定义字段类型是多行文本，并且可能包含HTML内容（例如，通过富文本编辑器输入），为了确保这些HTML代码能正确渲染而不是被转义成纯文本，你需要使用|safe过滤器：

    <div>产品特色：{{archive.feature_description|safe}}</div>

  • 图片类型： 如果你的自定义字段是一个图片（例如，通过自定义字段上传的商品细节图），它的Value会是一个图片URL。如果你希望显示多张图片，那么在定义字段时，通常会配置为支持多图上传的类型，此时item.Value可能是一个图片URL数组。

    ”`twig {# 假设你定义了一个“调用字段”为 arcimages，它存储了一个图片URL数组 #} 

    {% archiveDetail arcimages with name="arcimages" %}
{% for img_url in arcimages %}
    <img