在安企CMS中，内容管理不仅限于预设的标题、内容等字段，更可以通过自定义参数来丰富和扩展文档信息。当您为文章、产品或其他内容模型设置了独有的自定义字段时，如何在前端模板中准确地获取并展示这些特定名称的参数，是模板制作中常见的需求。本文将深入探讨如何利用archiveParams标签，灵活地获取并显示文档的自定义参数。

自定义参数的设定：一个简要回顾

在深入archiveParams标签之前，我们先快速回顾一下自定义参数的设定。在安企CMS后台，您可以进入“内容管理”模块下的“内容模型”设置，选择或创建一个内容模型。在这里，您可以添加各种类型的自定义字段，如单行文本、数字、多行文本、单项选择、多项选择、下拉选择等。这些字段就是我们所说的“自定义参数”，它们使得每个文档能够承载更多个性化的信息。

archiveParams标签的核心作用

archiveParams标签是安企CMS模板中专门用于获取当前文档或指定文档的自定义参数的工具。它能够将后台为文档配置的所有自定义字段，以可编程的方式提供给前端模板使用，极大地增强了模板的灵活性和内容的表现力。

这个标签通常需要包裹在{% archiveParams ... %}和{% endarchiveParams %}之间，用来定义一个变量来承载获取到的参数数据。

archiveParams标签的关键参数

archiveParams标签提供了一些参数，帮助您精确地获取所需数据：

  • id：这个参数用于指定您想要获取参数的文档ID。如果您在文档详情页使用archiveParams标签，且不指定id参数，它会默认获取当前页面的文档参数。如果您想获取其他文档的参数，则需要明确指定其ID，例如id="10"。
  • sorted：这是一个非常关键的参数，它决定了返回的数据结构。
    • 当sorted=true（默认值）时，archiveParams会返回一个有序的数组对象。数组中的每个元素都是一个包含Name和Value属性的对象，其中Name是自定义字段的显示名称，Value是其对应的值。这种模式适合您想要遍历并显示文档所有自定义参数的场景。
    • 当sorted=false时，archiveParams会返回一个无序的Map（键值对）对象。这个Map的键是自定义字段的“调用字段”（在后台内容模型中定义的英文名称），值则是一个包含Name和Value属性的对象。这种模式适合您已经知道自定义字段的调用字段名称，并希望直接访问特定参数的场景。
  • siteId：在多站点管理的环境下，如果您需要调用其他站点的文档参数，可以通过siteId参数指定目标站点的ID。通常情况下，此参数无需填写。

如何获取并显示特定名称的自定义参数？

了解了sorted参数的区别后，我们来看看两种主要的获取方式。

方式一：遍历所有自定义参数（sorted=true）

当您希望在文档页脚、侧边栏或专门的“参数列表”区域显示文档的所有自定义参数时，sorted=true模式（也是默认模式）非常实用。它返回一个数组，您可以方便地使用for循环来遍历。

假设您在后台定义了“作者”、“出版社”、“ISBN”等自定义字段，它们将以数组形式返回：

{% archiveParams customFields %}
    {% if customFields %} {# 建议添加判断，只有存在自定义参数时才显示 #}
    <div class="custom-params-list">
        <h3>文档额外信息</h3>
        <ul>
        {% for item in customFields %}
            <li>
                <strong>{{ item.Name }}：</strong>
                <span>{{ item.Value }}</span>
            </li>
        {% endfor %}
        </ul>
    </div>
    {% endif %}
{% endarchiveParams %}

在这段代码中，item.Name会显示您在后台设置的“参数名”（如“作者”），而item.Value则会显示该参数对应的内容（如“张三”）。

方式二：直接获取特定名称的自定义参数（sorted=false）

如果您已经明确知道某个自定义参数的“调用字段”名称，并且只想显示这一个参数，sorted=false模式能让您更直接地获取。

例如，您在后台内容模型中定义了一个名为“author”（调用字段）的自定义字段。您可以通过以下方式直接获取其值：

”`twig {% archiveParams paramsMap with sorted=false %}