`archiveParams`标签返回的自定义参数，其数据结构是固定数组还是可变Map？

您好，各位网站运营专家和安企CMS爱好者！

今天，我们将深入探讨安企CMS模板开发中的一个实用且灵活的标签——archiveParams。许多在使用自定义参数时，都会有一个疑问：archiveParams 标签返回的自定义参数，其数据结构究竟是固定数组还是可变Map？

为了更好地利用安企CMS强大的内容模型自定义能力，理解这一点至关重要。本文将为您详细解析 archiveParams 的数据结构，并提供实用的场景示例，帮助您在网站运营和模板设计中游刃有余。

揭秘 archiveParams：自定义参数的灵活数据结构

安企CMS以其高度的灵活性著称，尤其是在内容模型方面，允许我们为文章、产品等内容类型自定义丰富的字段。这些自定义字段，如文章作者、产品尺寸、特定属性等，极大地扩展了内容的表达形式。而 archiveParams 标签，正是我们从模板中访问这些宝贵自定义数据的关键。

当我们谈论 archiveParams 返回的数据结构时，答案并非非此即彼。实际上，它兼具了“固定有序列表”（在Go语言中常称为Slice或Array）和“可变键值对集合”（即Map）的特性，这取决于您如何配置和使用这个标签。

其核心在于 archiveParams 标签提供了一个名为 sorted 的参数，正是这个参数决定了返回的数据结构。

场景一：获取有序列表的自定义参数 (sorted=true 或默认)

当您在 archiveParams 标签中使用 sorted=true 参数，或者不指定 sorted 参数（因为 true 是其默认值）时，archiveParams 将会返回一个固定排序的列表（Slice/Array）。

这个列表中的每一个元素，都是一个包含 Name（字段名称，即后台显示的中文名）和 Value（字段数据）的对象。这种结构特别适合于：

1. 动态展示所有自定义字段： 比如，您可能想在一个产品详情页统一展示所有产品的规格参数，而这些参数的种类可能会随着后台内容模型的更新而增加。使用列表形式，您可以轻松地通过 for 循环遍历所有字段，而无需预知每个字段的具体名称。
2. 维护字段显示顺序： 如果后台自定义字段的定义顺序对前端展示很重要，那么 sorted=true 就能保证您获取到的数据是按照后台定义的顺序排列的。

示例代码（返回有序列表）：

假设您的后台内容模型定义了“作者”、“出版社”、“ISBN”等自定义字段。

{# 默认或显式指定 sorted=true，返回一个有序的列表 #}
<div>
    <h3>文档自定义参数（有序列表）：</h3>
    {% archiveParams params %} {# sorted=true 是默认行为 #}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span> {# 访问字段的显示名称 #}
        <span>{{item.Value}}</span> {# 访问字段的数据值 #}
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

{# 如果是特定文档的参数，可以指定id #}
<div>
    <h3>文档ID为1的自定义参数（有序列表）：</h3>
    {% archiveParams params with id="1" %}
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
    {% endarchiveParams %}
</div>

在这段代码中，params 变量是一个列表。通过 for 循环，我们可以迭代访问列表中的每一个自定义字段 item，并获取其显示名称 item.Name 和对应的值 item.Value。

场景二：获取键值对集合的自定义参数 (sorted=false)

当您在 archiveParams 标签中明确指定 sorted=false 时，archiveParams 将会返回一个无序的键值对集合（Map）。

在这种模式下，Map 的键是后台定义自定义字段时设置的“调用字段”（通常是英文小写字母），而Map的值同样是一个包含 Name 和 Value 的对象。这种结构非常适合于：

1. 精确访问特定自定义字段： 如果您知道某个自定义字段的“调用字段”名称（例如 author、product_image），并希望直接获取其值，而不需要遍历所有字段，那么Map结构提供了更直接、更高效的访问方式。
2. 与前端JS框架集成： 对于需要根据特定字段名进行数据绑定或逻辑处理的前端应用来说，Map结构的数据更易于处理。

示例代码（返回键值对集合）：

假设您的后台内容模型定义了一个调用字段为 isbn_number 的ISBN自定义字段，以及一个 author 的作者字段。

{# 显式指定 sorted=false，返回一个无序的Map #}
<div>
    <h3>文档自定义参数（键值对集合）：</h3>
    {% archiveParams params with sorted=false %}
        <div>
            <span>作者名称：</span>
            <span>{{params.author.Value}}</span> {# 通过键名直接访问作者字段的值 #}
        </div>
        <div>
            <span>ISBN：</span>
            <span>{{params.isbn_number.Value}}</span> {# 通过键名直接访问ISBN字段的值 #}
        </div>
        {# 也可以访问Name #}
        <div>
            <span>{{params.isbn_number.Name}}：</span>
            <span>{{params.isbn_number.Value}}</span>
        </div>
    {% endarchiveParams %}
</div>

在这里，params 变量是一个Map。我们可以通过 params.author.Value 或 params.isbn_number.Value 这种点操作符，根据自定义字段的调用字段名直接获取到它的值，无需循环。

如何选择适合您的数据结构？

选择哪种数据结构取决于您的具体需求：

• 选择有序列表（sorted=true，默认）：

  • 当您需要遍历所有自定义字段，并在前端统一展示，例如在一个“规格参数”区块中。
  • 当自定义字段的显示顺序对前端呈现很重要时。
  • 当您不确定所有自定义字段的调用字段名，或者字段类型可能动态变化时。

• 选择键值对集合（sorted=false）：

  • 当您需要精确获取某个或某几个特定自定义字段的值，例如文章的“来源”链接、产品的“视频介绍”URL。
  • 当您希望通过代码中的自定义字段名直接访问数据，提高模板的可读性和维护性。
  • 在与 JavaScript 等前端逻辑进行数据交互时，Map结构通常更为便捷。

总结

archiveParams 标签通过 sorted 参数提供了灵活的数据结构选择。无论是需要按序展示所有自定义参数，还是需要精确获取特定参数值，安企CMS都提供了高效且直观的解决方案。理解并善用这一特性，将大大提升您在安企CMS平台上的开发效率和内容运营能力。

常见问题 (FAQ)

Q1: 如何在安企CMS后台定义自定义参数？

A1: 自定义参数是在内容模型中定义的。您可以登录安企CMS后台，导航至 内容管理 -> 内容模型。选择或创建一个内容模型（例如“文章模型”或“产品模型”），然后点击“内容模型自定义字段”部分下的“添加字段”按钮。在这里，您可以设置字段的中文名（Name，用于前端 item.Name），调用字段（FieldName，用于 params.FieldName.Value 的 FieldName 部分），字段类型、是否必填、默认值等。定义完成后，该模型下的所有文档都将拥有这些自定义参数。

Q2: 如果我的自定义参数内容包含 HTML 标签，如何确保前端正确显示而不是被转义？

A2: 安企CMS的模板引擎出于安全考虑，默认会对输出内容进行 HTML 转义。如果您的自定义参数（例如一个富文本编辑器字段）中包含了 HTML 标签，并且您希望这些标签能被浏览器正常解析，而不是显示为原始的 <p> 或 <strong> 文本，您需要在输出时使用 |safe 过滤器。例如：<span>{{item.Value|safe}}</span> 或 <span>{{params.fieldName.Value|safe}}</span>。

Q3: 除了 archiveParams 标签，有没有其他方式直接获取某个特定的自定义参数值？