如何在 AnQiCMS 模板中调用自定义的文档额外参数（如文章作者、产品价格）？

在 AnQiCMS 的日常运营中，我们经常需要为不同类型的内容（例如文章、产品）添加一些标准字段之外的个性化信息，比如文章的特定作者、产品的详细价格、生产日期等。AnQiCMS 强大的内容模型功能允许我们灵活地定义这些自定义字段，并在模板中便捷地进行调用和展示，从而满足多样化的内容展示需求。

要实现这一目标，我们需要经历两个主要步骤：首先是在 AnQiCMS 后台定义这些自定义的额外参数，然后是在网站前端模板中正确地调用和展示它们。

定义文档的自定义额外参数

AnQiCMS 提供内容模型来自定义不同类型内容的结构。我们可以通过内容模型为文章、产品或其他自定义内容类型添加专属的字段。

首先，您需要登录 AnQiCMS 后台管理界面，导航至“内容管理”部分，然后选择“内容模型”。在这里，您可以看到系统内置的“文章模型”和“产品模型”，也可以创建新的自定义模型。选择您想要添加额外参数的模型，点击编辑进入详情页面。

在内容模型的编辑界面中，您会找到一个“内容模型自定义字段”的区域。这里是定义额外参数的核心所在。点击添加字段，您可以设置以下信息：

• 参数名：这是用于后台管理界面显示的字段名称，例如“文章作者”、“产品价格”或“生产日期”。
• 调用字段：这是在模板中调用此参数时使用的唯一标识符，通常建议使用英文小写字母，例如author、price或productionDate。这个字段名会直接映射到数据库，所以务必确保其唯一性和规范性。
• 字段类型：AnQiCMS 支持多种字段类型，如单行文本（适用于作者名、简单价格）、数字（适用于精确价格）、多行文本、单项选择、多项选择和下拉选择等。选择适合您数据类型的字段可以确保数据的准确性。
• 是否必填：根据业务需求设定该字段是否为必填项。
• 默认值：您可以为字段设置一个默认值。对于选择类型的字段，这里用于输入所有可选值，每行一个。

例如，如果您想为文章模型添加一个“文章作者”字段，您可以设置“参数名”为“文章作者”，“调用字段”为author，“字段类型”为“单行文本”。如果您想为产品模型添加一个“产品价格”，您可以设置“参数名”为“产品价格”，“调用字段”为price，“字段类型”为“数字”或“单行文本”（如果价格包含货币符号）。

完成字段定义后，保存内容模型。

填写自定义额外参数的数据

当内容模型中定义了自定义字段后，在您添加或编辑属于该模型下的文档时，这些自定义字段就会出现在文档编辑页面。

在后台创建或编辑文档时，您会看到一个名为“其他参数”的折叠区域。展开这个区域，您会发现您在内容模型中定义的所有自定义字段。例如，如果您为文章模型添加了author字段，那么在编辑文章时，这里就会出现一个“文章作者”的输入框，供您填写具体的作者名称。同样，产品模型下的price字段也会以相应的方式展示。

您只需根据文档的实际情况，在这些自定义字段中填入相应的数据即可。这些数据将在前端模板中被调用和展示。

在 AnQiCMS 模板中调用自定义额外参数

AnQiCMS 提供了两种主要的方式来在模板中调用文档的自定义额外参数：使用 archiveDetail 标签直接获取单个字段的值，或使用 archiveParams 标签遍历所有自定义字段。

使用 archiveDetail 标签获取单个自定义字段

当您明确知道要调用哪个自定义字段，并且只需要获取该字段的值时，archiveDetail 标签是最直接的选择。此标签通常用于文档详情页，它会默认获取当前文档的参数。

其基本用法是 {% archiveDetail with name="调用字段名" %}。

例如，如果您定义的文章作者的“调用字段”是author，那么在模板中，您可以这样调用并显示文章作者：

<div>文章作者：{% archiveDetail with name="author" %}</div>

如果您定义的产品的“调用字段”是price，那么您可以这样显示产品价格：

<div>产品价格：{% archiveDetail with name="price" %}</div>

您也可以将获取到的值赋给一个变量，以便在模板中更灵活地使用：

{% archiveDetail articleAuthor with name="author" %}
<div>作者：{{ articleAuthor }}</div>

{% archiveDetail productPrice with name="price" %}
<div>价格：{{ productPrice }}</div>

archiveDetail 标签还支持通过 id 或 token 参数指定获取特定文档的字段，但通常在文档详情页中，它会自动识别当前文档。

使用 archiveParams 标签遍历所有自定义字段

当您需要展示一个文档的所有自定义字段，或者需要以结构化的方式遍历这些字段时，archiveParams 标签会更加适用。此标签会将文档的所有自定义字段作为一个数组对象返回，您可以对其进行循环遍历。

其基本用法是 {% archiveParams 变量名称 %}，然后使用 for 循环来遍历这个变量。

例如，要显示一个文档的所有自定义参数：

{% archiveParams params %}
<div>
    {% for item in params %}
    <div>
        <span>{{ item.Name }}：</span> {# 参数名，如“文章作者” #}
        <span>{{ item.Value }}</span> {# 参数值，如“张三” #}
    </div>
    {% endfor %}
</div>
{% endarchiveParams %}

在上述代码中，params 是您自定义的变量名，它将包含一个包含所有自定义字段的数组。每个 item 在循环中都有 Name（即您在后台设置的“参数名”）和 Value（即您在文档中填写的参数值）两个属性。

archiveParams 标签有一个可选的 sorted 参数。当 sorted=true（默认值）时，它返回一个固定排序的数组对象，适合用 for 循环；当 sorted=false 时，它返回一个无序的 map 对象，您可以直接通过键（即“调用字段”）来访问：

{# 使用无序的map对象访问 #}
{% archiveParams params with sorted=false %}
<div>
    <div>作者：{{ params.author.Value }}</div>
    <div>价格：{{ params.price.Value }}</div>
</div>
{% endarchiveParams %}

这种方式在您需要直接访问特定自定义字段而不是遍历所有字段时非常方便。

在文档列表循环中调用自定义字段

如果您在使用 archiveList 标签循环展示多个文档时，也希望显示每个文档的自定义字段，您可以在 archiveList 的循环内部嵌套使用 archiveParams 标签，并传入当前文档的 Id。

{% archiveList archives with type="page" limit="10" %}
    {% for archiveItem in archives %}
    <div>
        <h3><a href="{{ archiveItem.Link }}">{{ archiveItem.Title }}</a></h3>
        {# 在这里调用当前文档的自定义参数 #}
        {% archiveParams currentArchiveParams with id=archiveItem.Id %}
        <div>
            {% for param in currentArchiveParams %}
                <span>{{ param.Name }}：{{ param.Value }}</span>
            {% endfor %}
        </div>
        {% endarchiveParams %}
    </div>
    {% endfor %}
{% endarchiveList %}

通过以上方法，您便可以在 AnQiCMS 模板中灵活地定义、填写和调用自定义的文档额外参数，从而实现更丰富和个性化的内容展示。

常见问题解答

为什么我设置的自定义字段在模板中调用不出来？

首先，请确保您在内容模型中定义的“调用字段”名称与模板中name参数的值完全一致，包括大小写。AnQiCMS 的模板标签对大小写是敏感的。其次，检查您是否在编辑文档时，为该自定义字段填写了数据，如果字段为空，在前端自然不会显示任何内容。最后，请确认您调用自定义字段的文档是否属于您定义了这些字段的内容模型。

如何在文档列表中显示自定义字段？

要在文档列表（通过 archiveList 标签获取的列表）中显示每个文档的自定义字段，您需要在 archiveList 的 for 循环内部嵌套使用 archiveParams 标签。在调用 archiveParams 时，务必通过 id 参数将当前循环文档的 Id 传递进去，例如 {% archiveParams params with id=item.Id %}，其中item是archiveList循环中的当前文档变量。

我可以直接在 archiveDetail 标签里调用自定义字段吗？

是的，您可以直接在 archiveDetail 标签里通过 name 参数指定您自定义字段的“调用字段”名称来获取其值。例如，如果您有一个名为 productWeight 的自定义字段，您可以直接使用 {% archiveDetail with name="productWeight" %} 来获取并显示它。这是获取单个特定自定义字段最简洁的方式。