作为一位资深的网站运营专家，我很乐意为您详细阐述安企CMS中 archiveParams 标签的 id 参数如何用于获取特定文档的自定义字段。安企CMS以其灵活的内容模型和强大的模板标签系统，为内容运营提供了极大的便利。掌握这些标签的精髓，能让您的网站内容展示更加个性化，运营效率倍增。

深入挖掘内容潜能：使用 archiveParams 标签获取特定文档的自定义字段

在安企CMS的强大功能矩阵中，自定义字段（或称模型字段）无疑是提升内容灵活性和个性化展示的关键。它允许您为不同类型的内容（如文章、产品、案例等）定义独有的属性，从而摆脱传统CMS固定字段的束缚。但如何精准地获取这些特定字段，特别是当您需要展示某个指定文档的额外信息时，就显得尤为重要了。今天，我们将聚焦于 archiveParams 标签及其核心参数 id，揭示其在获取特定文档自定义字段方面的强大能力。

灵活的基石：安企CMS的自定义字段

安企CMS之所以能满足多样化的内容展示需求，很大程度上得益于其“灵活的内容模型”设计。这意味着您可以根据业务场景，在后台为不同的内容模型（例如，文章模型可能包含“作者”、“来源”字段；产品模型可能包含“价格”、“库存”、“材质”字段）创建任意数量的自定义字段。这些字段可以涵盖单行文本、数字、多行文本，甚至单选、多选和下拉选择等多种类型，极大地丰富了内容的表达维度。在文档发布时，编辑人员便能为每篇文档填入这些独特的属性值。

archiveParams 标签：自定义字段的聚合器

archiveParams 标签是安企CMS模板系统中专门用于获取文档自定义字段的利器。它能够将后台为文档模型定义的那些额外字段及其对应的值，以编程友好的方式提供给模板进行渲染。

通常情况下，当您在文档详情页使用 {% archiveParams params %} 这样的方式调用时，它会自动识别当前页面的文档ID，并返回该文档的所有自定义字段。但在很多场景下，我们可能需要在非当前文档详情页的地方，获取到特定文档的自定义字段。这时，id 参数就登场了。

精准定位：id 参数的魔法

archiveParams 标签的 id 参数，允许您明确指定要获取哪个文档的自定义字段。这就像给标签指明一个目标，让它不再“盲目”地获取当前文档，而是直奔您预设的文档而去。

举个例子，假设您网站有一个“热门产品”区域，需要展示某个特定产品的“型号”和“特点”等自定义字段。这个“热门产品”区域可能出现在首页，而不是该产品本身的详情页。此时，您就可以通过 id 参数来精确地获取目标产品的自定义字段：

{# 假设我们已知要获取ID为123的产品文档的自定义字段 #}
{% archiveParams specificDocParams with id="123" %}
    <p>以下是ID为123文档的自定义字段：</p>
    {% for item in specificDocParams %}
        <div>
            <span>{{ item.Name }}：</span>
            <span>{{ item.Value }}</span>
        </div>
    {% endfor %}
{% endarchiveParams %}

在这段代码中，with id="123" 明确告诉 archiveParams 标签去获取ID为123的文档的自定义字段。这些字段会存储在 specificDocParams 变量中，然后通过 for 循环遍历，展示出每个自定义字段的名称（item.Name）和值（item.Value）。

两种获取模式：有序数组与无序映射

archiveParams 标签在返回自定义字段时，提供了两种结构模式，这取决于 sorted 参数的设置：

  1. 有序数组 (sorted=true，默认行为)： 当 sorted 参数为 true（或不设置，因为这是默认值）时，archiveParams 返回一个包含自定义字段的数组。数组中的每个元素都是一个对象，包含 Name（字段的显示名称）和 Value（字段的值）。这种模式非常适合通过 for 循环遍历并显示所有或部分自定义字段。

    {# 默认行为，sorted=true #}
{% archiveParams docDetails with id="456" %}
    <h3>文档ID 456 的详细参数（有序列表）：</h3>
    <ul>
        {% for field in docDetails %}
            <li><strong>{{ field.Name }}：</strong> {{ field.Value }}</li>
        {% endfor %}
    </ul>
{% endarchiveParams %}

  2. 无序映射 (sorted=false)： 如果您明确知道自定义字段的“调用字段”（即在后台定义时使用的英文字段名，而非显示名称），并且希望直接通过字段名访问，那么可以将 sorted 参数设置为 false。此时，archiveParams 返回一个映射（map）对象，其键（key）就是自定义字段的调用字段名。

    {# 假设文档ID 789 有一个调用字段名为 'material' 的自定义字段 #}
{% archiveParams docMap with id="789" sorted=false %}
    <h3>文档ID 789 的特定参数（通过字段名直接访问）：</h3>
    <p>产品材质：{{ docMap.material.Value }}</p>
    {# 假设还有一个 'warranty_period' 字段 #}
    {% if docMap.warranty_period %}
        <p>保修期：{{ docMap.warranty_period.Value }}</p>
    {% endif %}
{% endarchiveParams %}

    这种方式在您需要快速获取少量特定自定义字段时非常高效，无需遍历整个列表。请注意，docMap.material.Value 中的 material 是自定义字段的“调用字段”，而非“参数名”。

archiveDetail 标签的互补性

值得一提的是，如果您只需要获取某个特定文档的单个自定义字段，安企CMS还提供了另一种更为简洁的方式，即直接使用 archiveDetail 标签的 name 参数来指定自定义字段的调用字段名。

{# 直接获取文档ID 123 的 'author' 自定义字段 #}
<p>文档作者：{% archiveDetail with name="author" id="123" %}</p>

{# 获取文档ID 123 的 'release_date' 自定义字段，并格式化时间 #}
{% archiveDetail releaseDate with name="release_date" id="123" %}
<p>发布日期：{{ stampToDate(releaseDate, "2006年01月02日") }}</p>

这种方式在您已经明确知道要获取哪个自定义字段时，会比 archiveParams 更加直接和精炼。

实战建议

  • 灵活运用 id： 不论是在首页侧边栏、专题页面，还是相关推荐模块，只要您需要展示某个指定文档的独特属性，id 参数都能派上用场。
  • 根据需求选择获取模式： 如果您需要展示一篇文档的所有自定义字段，或者需要按特定顺序展示，sorted=true 的 archiveParams 配合 for 循环是**选择。如果您需要快速访问文档的少数几个已知自定义字段，sorted=false 的 archiveParams 或 archiveDetail 标签则更为高效。
  • 注意字段名大小写： 在使用 archiveParams 的无序映射模式或 archiveDetail 标签直接获取自定义字段时，请确保您使用的字段名（即“调用字段”）与后台定义时的大小写完全一致，否则可能无法获取到数据。

通过 archiveParams 标签及其 id 参数的灵活运用，您将能够更自如地驾驭安企CMS的内容展示，为用户带来更丰富、更精准的网站体验。

常见问题 (FAQ)

  1. Q: 我如何知道一个自定义字段的“调用字段”（FieldName）是什么？ A: 在安企CMS后台，进入“内容管理” -> “内容模型”，选择您定义了自定义字段的模型。编辑该模型，您会看到每个自定义字段的设置，其中会有一个“调用字段”或“字段名”的选项（通常是英文字母）。这个名称就是您在模板中直接访问该字段时需要使用的键名。例如，如果您在后台为“产品模型”定义了一个名为“材质”的自定义字段，其调用字段设置为 material，那么在模板中就可以用 docMap.material.Value 或 {% archiveDetail with name="material" %} 来获取。

  2. Q: archiveParams 和 archiveDetail 标签在获取自定义字段时有什么区别和**使用场景？ A:

    • archiveParams: 主要用于获取一个文档的所有（或多个）自定义字段。
      • 当 sorted=true 时，返回一个包含 Name 和 Value 的有序数组，适合遍历展示所有自定义字段，特别是当您需要显示字段的“显示名称”时。
      • 当 sorted=false 时，返回一个以“调用字段”为键的无序映射，适合已知字段名时直接获取。
    • archiveDetail: 主要用于获取一个文档的单个字段（包括常规字段如 Title、Content，