在网站内容管理中，我们经常需要为不同类型的信息定义独特的属性，以满足网站多样化的展示需求。安企CMS提供了强大的自定义参数功能，让您可以为文档（文章、产品等）灵活地添加额外信息。当您希望在网站前端模板中获取这些自定义参数，并按照在后台设置的固定顺序进行展示时，安企CMS内置的模板标签能够很好地帮助您实现这一点。

理解文档的自定义参数

安企CMS允许您通过内容模型为不同的文档类型（如文章、产品）创建专属的自定义字段。这些字段可以包括作者、来源、特定产品的规格、活动时间等。这些自定义参数的优势在于，它们不仅丰富了文档信息，而且可以根据业务需求灵活定义字段类型（如单行文本、数字、多行文本、单选、多选、下拉选择等），极大地提升了内容管理的灵活性和网站的适应性。

核心工具：archiveParams 标签

要在模板中获取一个文档的所有自定义参数，并确保它们按照您在后台配置的顺序显示，我们需要用到安企CMS模板引擎提供的一个专用标签——archiveParams。这个标签专为获取文档的附加参数而设计，尤其擅长处理有序的参数列表。

如何使用 archiveParams 标签

archiveParams 标签的基本使用方式是将其包裹在一个 {% archiveParams params %} 和 {% endarchiveParams %} 块中。在这里，params 是您自定义的一个变量名，它将用于存储获取到的所有自定义参数。

默认情况下，archiveParams 标签会以您在后台“内容模型”中设置的顺序，返回一个包含每个自定义参数的列表。列表中的每个参数都是一个对象，包含两个主要属性：

  • Name：表示该自定义参数的显示名称（例如“文章作者”、“产品型号”）。
  • Value：表示该自定义参数的具体值（例如“张三”、“X-Pro 2023”）。

下面我们通过一个示例来详细说明如何在模板中使用这个标签。

模板中的实践

假设您已经在后台为某个内容模型（比如“产品模型”）定义了“产品型号”、“颜色”、“材质”等自定义参数。现在，您希望在产品详情页显示这些参数。

您可以在产品详情页的模板文件（通常是 {模型table}/detail.html 或自定义的文档模板）中添加以下代码片段：

{# 假设您正在产品详情页，并且当前文档对象已被正确加载 #}

<div class="product-specs">
    <h3>产品参数</h3>
    {% archiveParams productParams %} {# productParams 是您自定义的变量名 #}
        {% if productParams %} {# 检查是否存在自定义参数 #}
            <ul>
                {% for item in productParams %}
                    {# 遍历每一个自定义参数，item.Name 是参数名称，item.Value 是参数值 #}
                    <li>
                        <strong>{{ item.Name }}：</strong>
                        <span>{{ item.Value }}</span>
                    </li>
                {% endfor %}
            </ul>
        {% else %}
            <p>暂无其他产品参数信息。</p>
        {% endif %}
    {% endarchiveParams %}
</div>

在这段代码中：

  1. 我们首先使用 {% archiveParams productParams %} 标签来获取当前文档的所有自定义参数，并将它们赋值给名为 productParams 的变量。
  2. {% if productParams %} 用于判断是否有任何自定义参数存在，避免在没有参数时显示空的列表。
  3. {% for item in productParams %} 循环遍历 productParams 变量中的每一个参数。由于 archiveParams 默认就是按照后台设置的顺序返回参数，因此这里的 item 将按照您在内容模型中定义的顺序依次出现。
  4. 在循环内部，{{ item.Name }} 会显示参数的名称（如“产品型号”），而 {{ item.Value }} 则会显示该参数的具体值（如“AnQiCMS Pro”）。

通过这种方式，您不仅能够轻松获取文档的所有自定义参数，还能确保它们以一种结构化且有序的方式呈现在用户面前，这对于产品规格、技术文档等需要严格遵循特定信息展示顺序的场景尤为重要。

获取指定文档的自定义参数

上述示例默认获取当前正在浏览的文档的参数。如果您需要获取其他指定文档的自定义参数，例如在一个相关推荐模块中，您可以通过 id 参数来指定文档的 ID：

{# 假设您要获取 ID 为 123 的文档的自定义参数 #}
<div class="related-document-specs">
    <h4>相关文档（ID: 123）参数</h4>
    {% archiveParams specificDocParams with id="123" %}
        {# 同样可以通过循环遍历 specificDocParams 来显示其内容 #}
        {% for item in specificDocParams %}
            <p>{{ item.Name }}: {{ item.Value }}</p>
        {% endfor %}
    {% endarchiveParams %}
</div>

关于参数排序的强调

archiveParams 标签默认情况下就会按照您在后台“内容模型”中配置的字段顺序来返回参数列表。这意味着您无需额外设置 sorted=true（尽管文档中提到了这个参数，但因为它是默认行为，所以通常可以省略）。如果您确实需要不保证顺序的键值对形式访问（例如，直接通过字段名访问某个特定参数，而不关心它在列表中的位置），可以将 sorted 参数设置为 false，但对于按固定顺序显示的需求，保持默认或明确 sorted=true 即可。

总结来说，安企CMS的 archiveParams 标签是一个高效且直观的工具，它让在模板中展示文档的自定义参数变得异常简单，并且完全尊重您在后台设置的显示顺序，从而大大提升了模板制作的效率和内容的表现力。

常见问题 (FAQ)

  1. 问：我只想显示某个特定的自定义参数，而不是所有参数，该怎么做？ 答：如果您只需要显示单个自定义参数，可以使用 archiveDetail 标签并指定参数名。例如，如果您有一个名为 product_model 的自定义参数，可以直接在模板中这样调用：{% archiveDetail with name="product_model" %}。这种方式更直接，无需循环遍历所有参数。
  2. 问：如果某个自定义参数没有填写内容，我希望它不显示，应该如何处理？ 答：在循环 productParams 变量时，您可以在 {% for item in productParams %} 循环内部添加一个条件判断。例如，{% if item.Value %}。这样，只有当 item.Value 存在内容时，才会显示该参数的名称和值。
  3. 问：除了文档详情页，我能否在其他页面（例如列表页）获取文档的自定义参数？ 答：可以的。archiveParams 标签可以使用 id 参数来指定任何文档的 ID，从而获取该文档的自定义参数。这意味着您可以在任何需要的地方（如列表页循环中的每个文档项内，或相关推荐区块）通过提供文档ID来调用这个标签，获取并展示指定文档的自定义参数。但请注意，在列表页中为每个列表项都调用 archiveParams 可能会增加页面加载时间，建议根据实际需求和性能考虑进行优化。