`archiveParams`标签如何获取并灵活显示文档模型中的自定义参数字段？

在安企CMS中管理内容时，我们经常会遇到需要为不同类型的内容（如文章、产品）添加特定属性的情况。安企CMS提供的“内容模型”功能，允许我们根据业务需求自定义字段，极大地增强了内容的灵活性和可扩展性。那么，如何在网站前台模板中，优雅而灵活地获取并展示这些自定义参数字段呢？archiveParams 标签便是解答这个问题的关键。

理解文档模型中的自定义参数

在深入探讨 archiveParams 标签之前，我们先回顾一下安企CMS内容模型中自定义参数的设定。通过后台的“内容管理” -> “内容模型”功能，我们可以为每个内容模型（例如“文章模型”或“产品模型”）添加独有的自定义字段。这些字段可以包含各种类型，比如单行文本（作者、来源）、数字（价格、库存）、多行文本（产品特性）、单选/多选框（颜色、尺码）等等。这些自定义字段为我们的内容管理提供了强大的个性化能力。

archiveParams 标签：灵活获取自定义字段的利器

当我们希望在前端页面展示一篇文档的所有或部分自定义参数时，archiveParams 标签便派上了用场。它允许我们获取当前文档或指定文档的所有自定义参数，并提供两种主要的方式来组织这些数据，以满足不同的展示需求。

获取当前文档的自定义参数

archiveParams 标签通常在文档详情页中使用，此时它会默认获取当前正在浏览的文档的自定义参数。其基本用法如下：

{% archiveParams params %}
    {# 循环遍历所有自定义参数 #}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
{% endarchiveParams %}

在这段代码中，params 是我们为获取到的自定义参数集合定义的变量名。通过 for 循环，我们可以逐一访问每个自定义参数，item.Name 会显示参数的名称（例如“作者”、“产品编号”），item.Value 则会显示该参数对应的值。这种方式非常适合当你需要列出文档的所有自定义属性时，而无需预先知道每个属性的具体名称。

指定文档ID获取参数

如果我们需要获取某个特定文档的自定义参数，而不是当前页面上的文档，可以利用 id 参数来指定文档的ID：

{% archiveParams specificParams with id="1" %}
    {# 循环遍历ID为1的文档的所有自定义参数 #}
    {% for item in specificParams %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
{% endarchiveParams %}

这里，id="1" 将会获取文档ID为1的所有自定义参数。

灵活的数据组织方式：sorted 参数的妙用

archiveParams 标签的 sorted 参数是其灵活性的关键所在。它决定了获取到的自定义参数是以固定排序的数组形式呈现，还是以无序的键值对（map）形式呈现。

  1. sorted=true (默认行为): 固定排序的数组

    当 sorted 参数设置为 true（这也是默认行为，可以省略不写）时，archiveParams 会返回一个数组对象。数组中的每个元素都是一个包含 Name 和 Value 字段的对象。这意味着你可以按照在后台内容模型中定义的顺序或系统默认的顺序，依次遍历并显示这些参数。这种方式非常适合于希望统一展示所有自定义字段的场景，例如产品详情页面的“产品规格”列表。

    {# 默认行为，或明确指定 sorted=true，获取一个固定排序的数组 #}
<div>
    <h3>产品规格</h3>
    {% archiveParams productSpecs %}
    {% for spec in productSpecs %}
    <div>
        <strong>{{spec.Name}}：</strong>
        <span>{{spec.Value}}</span>
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

  2. sorted=false: 无序的map对象，直接访问

    当 sorted 参数设置为 false 时，archiveParams 会返回一个map对象。这个map的键就是你在内容模型中为自定义字段设定的“调用字段”（例如 author、source 等），值则是包含 Name 和 Value 的对象。这种方式的优势在于你可以直接通过字段名访问特定参数，而不需要进行循环遍历。它特别适用于你只需要显示文档的某个或某几个特定自定义字段，并且这些字段的“调用字段”名称是已知的情况。

    {# 获取一个无序的map对象，直接通过调用字段名访问 #}
{% archiveParams articleInfo with sorted=false %}
    <div>
        <span>作者：</span>
        <span>{{articleInfo.author.Value}}</span> {# 假设调用字段名为 'author' #}
    </div>
    <div>
        <span>来源：</span>
        <span><a href="{{articleInfo.sourceUrl.Value}}" target="_blank">{{articleInfo.source.Value}}</a></span> {# 假设调用字段名为 'source' 和 'sourceUrl' #}
    </div>
{% endarchiveParams %}

    通过 articleInfo.author.Value 这样的语法，可以直接获取到“作者”这个自定义字段的值。这在需要将自定义字段嵌入到特定HTML结构中，而不是统一列表显示时，显得尤为方便。

多站点环境下的应用

如果你的安企CMS部署了多站点功能，并且希望获取非当前站点的文档参数，可以使用 siteId 参数来指定站点ID。这在构建跨站点内容聚合或展示时非常有用，但对于单站点应用通常无需关心。

archiveParams 与 archiveDetail 的区别

值得一提的是，安企CMS中的 archiveDetail 标签，虽然主要用于获取文档的基本信息（标题、内容等），但它也可以直接获取单个自定义字段的值。例如，如果你只需要获取一个名为 author 的自定义字段，可以直接使用 {% archiveDetail with name="author" %}。

那么，何时选择 archiveParams，何时选择 archiveDetail 来获取自定义字段呢？

  • 当你需要遍历显示所有或大部分自定义字段，或者不确定有哪些自定义字段时，archiveParams 是**选择（配合 sorted=true）。
  • 当你需要获取并精确控制某个特定自定义字段的显示位置和方式时，archiveParams 配合 sorted=false 进行直接访问，或使用 archiveDetail 直接获取该字段值，都是不错的选择。archiveDetail 更加简洁，但 archiveParams (sorted=false) 可以一次性获取所有自定义字段的map，方便后续按需挑选使用，减少标签调用次数。

总而言之，archiveParams 标签为安企CMS用户提供了强大而灵活的自定义字段展示能力，无论是统一罗列还是精确调用，都能轻松应对，让您的网站内容展示更加丰富和个性化。

常见问题（FAQ）

1. 我在内容模型中自定义了一个图片字段（例如：产品图集，调用字段名为 product_gallery），archiveParams 如何获取并显示它？

答：如果您的自定义图片字段存储的是图片URL的JSON数组，那么当您使用 archiveParams 获取并循环显示时，item.Value 将会是这个JSON字符串。您需要结合split、json或直接利用模板引擎的特定处理方式（如果它能自动识别）来解析它。例如，如果 item.Value 直接是一个逗号分隔的URL字符串，您可以 {{ item.Value|split:"," }} 得到一个数组再循环。更常见的是，如果后台存储的是json字符串，模板可能需要一个特殊的过滤器或者在后台处理成更友好的格式。在安企CMS中，如果自定义字段被设计为“组图”类型，archiveDetail 标签可以直接像处理 Images 字段一样处理它，而 archiveParams 获取到的 item.Value 可能是JSON字符串，需要您手动解析或依赖框架对自定义字段值的自动解析能力。通常情况下，AnQiCMS会将自定义的组图字段直接渲染成可循环的数组，例如：

{% archiveParams productDetails with sorted=false %}
    {% if productDetails.product_gallery %} {# 检查是否存在此自定义字段 #}
        <h3>产品图集</h3>
        <div class="product-gallery">
            {% for imageUrl in productDetails.product_gallery.Value %} {# 假设 Value 已经是可循环的图片URL数组 #}
                <img src="{{ imageUrl }}" alt="产品图片">
            {% endfor %}
        </div>
    {% endif %}
{% endarchiveParams %}

请注意，这里的 productDetails.product_gallery.Value 能够直接循环，是依赖于AnQiCMS模板引擎对特定类型自定义字段（如组图）的智能解析。如果您的自定义字段是纯文本，即使内容是JSON，也需要手动解析。

2. 为什么我使用 archiveParams 标签获取自定义字段时，某些字段没有显示出来？

答：请检查以下几点：

  • 文档是否真的保存了该字段的值？ 有些自定义字段可能在添加文档时没有填写内容，或者内容为空。
  • 字段是否设置为“显示在列表”或“可筛选”？ 虽然 archiveParams 通常获取的是所有字段，但某些后台配置（如“在列表页隐藏”等）可能会影响前端的显示。确保您在内容模型中定义的自定义字段是“可用于模板调用”的。
  • “调用字段”名称是否正确？ 如果您使用 sorted=false 尝试直接访问，例如 {{articleInfo.author.Value}}，请确保 author 是该自定义字段在内容模型中设定的准确“调用字段”名称（通常为英文小写）。
  • 模板缓存问题： 尝试清除安企CMS的系统缓存，有时候模板文件或数据更新后，旧的缓存可能导致显示异常。

3. 如何在 archiveParams 中过滤或只显示特定类型的自定义字段？

答：archiveParams 标签本身不提供直接的字段类型过滤功能。但您可以通过两种方式实现：

  • 后台控制： 在内容模型设置中，您可以选择哪些自定义字段是“必填”、“显示在发布页”等，这会影响字段的录入，但通常不直接过滤前端显示。

  • 模板内逻辑判断： 在 {% for item in params %} 循环中，您可以添加条件判断来筛选要显示的字段。例如，如果您想跳过显示名为“内部备注”的字段：

    {% archiveParams params %}
    {% for item in params %}
        {% if item.Name != '内部备注' %}
            <div>
                <span>{{item.Name}}：</span>
                <span>{{item.Value}}</span>
            </div>
        {% endif %}
    {% endfor %}
{% endarchiveParams %}

    这种方式可以根据 item.Name（显示名称）或 item.FieldName（调用字段名，需通过特定方式获取或预知）来灵活控制显示。