`archiveParams`标签如何将文档的自定义字段数据呈现在前端页面？

在安企CMS中，内容的灵活性是我们进行网站运营和内容管理的核心优势之一。除了标题、正文等标准化字段，我们经常需要为不同类型的内容添加特定的自定义信息，比如产品的“品牌”、“型号”、“产地”，或者文章的“作者”、“来源”等。这些自定义字段极大地丰富了内容展示的维度，但如何将这些精心录入的后台数据准确、灵活地呈现在前端页面上，是模板开发时一个重要的考量。

这时，安企CMS提供的archiveParams标签就派上了大用场。它专门用于获取并展示文档（文章、产品等内容模型）后台设置的这些自定义字段数据，让你的网站内容展示更具个性化和实用性。

理解自定义字段与archiveParams的桥接作用

在安企CMS的后台，我们可以在“内容模型”中为不同的内容类型（例如“文章”模型或“产品”模型）定义一系列独有的自定义字段。当你在添加或编辑一篇文档时，这些自定义字段会作为“其他参数”出现在编辑界面，供你填写额外的信息。

archiveParams标签就如同一个智能的桥梁，它能够理解你为文档定义的这些后台参数，并将它们安全地提取出来，供你在前端模板中使用。无论是你想罗列所有参数，还是只关注其中某一个特定参数，archiveParams都能帮你轻松实现。

archiveParams标签的基本用法

archiveParams标签的基本结构是{% archiveParams 变量名称 with 参数... %}{% endarchiveParams %}。通常，我们会在文档详情页（比如文章详情页或产品详情页）使用它，因为它默认会获取当前页面文档的自定义参数。

它支持几个关键参数来控制数据的获取方式：

• id：这个参数用来指定要获取哪个文档的自定义参数。如果你在文档详情页使用，通常可以省略id，它会自动获取当前文档的ID。但如果你想获取其他文档的参数，就可以通过id="文档ID"来明确指定。
• sorted：这是个非常实用的参数，它决定了你获取到数据是以哪种结构组织。
  • 当sorted=true（这也是默认值）时，archiveParams会返回一个按后台设置顺序排列的数组对象。这个数组中的每个元素都是一个包含Name（字段名称，即后台显示的中文名）和Value（字段值，即你填写的具体数据）的对象。
  • 当sorted=false时，它会返回一个无序的map对象。在这种模式下，你可以直接通过字段的“调用字段”（在内容模型中定义的英文名）来访问数据，例如params.your_field_name.Value。
• siteId：如果你使用了安企CMS的多站点管理功能，并且需要调用其他站点的数据，可以通过siteId来指定。一般情况下，我们不需要填写它。

两种主要的展示方式

掌握了archiveParams的参数，我们就可以根据需求选择不同的方式来展示自定义字段了。

1. 遍历所有自定义字段（适用于sorted=true，或不知道具体字段名时）

当你不确定一个文档到底有哪些自定义字段，或者你希望将所有定义过的参数都统一展示出来时，使用默认的sorted=true模式（或不写sorted参数），通过for循环遍历是个非常便捷的方法。

假设你在后台为产品定义了“品牌”、“型号”、“颜色”等自定义字段，在产品详情页的模板中，你可以这样来展示它们：

<div class="product-params">
    <h4>产品参数</h4>
    {% archiveParams params %}
        {% for item in params %}
        <p>
            <span>{{ item.Name }}：</span>
            <span>{{ item.Value }}</span>
        </p>
        {% endfor %}
    {% endarchiveParams %}
</div>

在这段代码中，params是一个包含所有自定义字段的数组。每次循环，item.Name会显示如“品牌”、“型号”这样的中文名称，而item.Value则会显示你后台填写的具体内容，比如“安企科技”、“AQ-CMS-001”、“黑色”等。这种方式非常适合在“产品参数”或“文章属性”等区域，动态地罗列所有相关信息。

2. 直接访问特定自定义字段（适用于sorted=false或archiveDetail标签）

如果你明确知道要展示的自定义字段的“调用字段”名称（例如，你定义了一个用于存储文章作者的字段，其“调用字段”是author），并且只想展示这一个字段，那么直接访问会更简洁高效。

方式一：利用archiveParams与sorted=false 将sorted参数设置为false，可以让你以类似字典（map）的方式直接通过“调用字段”名来获取值：

{% archiveParams params with sorted=false %}
    <p>作者：<span>{{ params.author.Value }}</span></p>
    <p>出版社：<span>{{ params.publisher.Value }}</span></p>
{% endarchiveParams %}

这里的author和publisher就是在内容模型中为这些自定义字段设置的“调用字段”名称。

方式二：通过archiveDetail标签直接获取 这是在文档详情页中最常用也最简洁的方式。安企CMS提供了一种更直接的途径，你无需使用archiveParams标签的循环结构，可以直接通过archiveDetail标签来获取单个自定义字段的值。

例如，在文章详情页，如果你有一个自定义字段的“调用字段”是author，你可以直接这样使用：

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

甚至，如果当前模板上下文已经包含了文档对象（通常在文档详情页会有一个名为archive的全局变量），你还可以直接通过点语法来访问自定义字段：

<p>作者：<span>{{ archive.author }}</span></p>
<p>产品型号：<span>{{ archive.product_model }}</span></p>

这种方式特别适合那些你频繁使用且名称固定的自定义字段，让模板代码更加清晰易读。

实战中的考量与小贴士

• 字段命名与调用： 在后台定义自定义字段时，建议“调用字段”使用简洁、有意义的英文小写字母或驼峰命名，以便在模板中方便调用（例如product_model或`product