如何显示文章模型中自定义的额外字段数据，实现灵活的内容展示？

在安企CMS中，内容的灵活性是其核心优势之一。我们常常需要展示超越标题、内容简介等标准字段的独特信息，例如产品的 SKU 编码、发布日期、作者信息，或是活动的具体时间地点等。这些个性化的数据，通过自定义额外字段功能，可以得到完美的承载和管理。但如何将这些精心录入的自定义数据，优雅且灵活地呈现在网站前台，则是许多用户关注的焦点。

本文将引导大家深入了解安企CMS中自定义字段的显示机制，让你能够游刃有余地控制内容的展示。

为什么自定义额外字段对内容展示至关重要？

安企CMS的“灵活的内容模型”功能，允许我们根据实际业务需求创建或修改内容模型，并为其添加任意数量的自定义字段。设想一下，如果你的网站需要展示一系列电子产品，除了产品名称和描述，你可能还需要：

  • 型号 (Model Number)：一个单行文本字段
  • 品牌 (Brand)：一个下拉选择字段
  • 保修期 (Warranty)：一个数字字段
  • 详细参数表 (Specification Table)：一个多行文本或富文本字段
  • 产品画廊 (Product Gallery)：一个图片组字段

通过自定义字段，这些信息可以与产品内容紧密绑定，极大丰富了内容的维度。更重要的是，它将内容结构化，为后续的前台样式设计和数据调用提供了极大的便利。

在安企CMS后台设置自定义字段

首先，我们需要在安企CMS后台为内容模型添加这些自定义字段。操作路径通常是：内容管理 -> 内容模型。

在这里，你可以选择现有的模型进行修改，或者创建全新的模型。进入模型的编辑界面后，你会看到“内容模型自定义字段”区域。点击添加字段，你需要填写以下关键信息：

  1. 参数名：这是字段在后台管理界面显示的名称，例如“产品型号”、“保修期”。
  2. 调用字段：这是字段在模板中被调用的唯一标识，建议使用有意义的英文小写字母，例如model_number、warranty_period。这个名称将在模板调用时用到，务必记住。
  3. 字段类型：根据数据特性选择合适的类型，如“单行文本”、“数字”、“多行文本”、“单项选择”、“多项选择”或“下拉选择”。如果你的字段内容需要包含HTML标记或Markdown语法，建议选择“多行文本”并在前端配合相应过滤器处理。
  4. 是否必填：根据需求设置。
  5. 默认值：如果字段有预设值，可以填写在此。对于选择类型的字段，默认值将作为选项列表，一行一个。

完成字段设置后，保存模型。之后，在发布或编辑该模型下的文章时，你就会在“其他参数”中看到这些自定义的额外字段，可以填入对应的数据了。

在模板中显示自定义字段数据

安企CMS的模板系统采用了Django-like语法，提供了灵活的标签和过滤器来处理数据。显示自定义字段主要有两种方式：

1. 显示单个自定义字段的数据

如果你知道自定义字段的“调用字段”名称，并且只需要显示特定的一两个字段，可以使用archiveDetail标签。这个标签通常用于获取当前文档的详细信息，但它也同样适用于获取自定义字段。

假设我们有一个自定义字段，其“调用字段”为product_sku，我们可以这样在模板中显示它的值：

{# 显示当前文档的名为 'product_sku' 的自定义字段值 #}
<div>产品SKU：{% archiveDetail with name="product_sku" %}</div>

{# 如果你想为这个值指定一个变量名，方便后续处理，可以这样做： #}
{% archiveDetail productSkuValue with name="product_sku" %}
<div>产品SKU：{{ productSkuValue }}</div>

{# 你也可以指定其他文档的自定义字段，通过 id 或 token 参数： #}
<div>指定ID文档的产品SKU：{% archiveDetail with name="product_sku" id="10" %}</div>

请注意，name参数的值就是你在后台设置的“调用字段”名称。

2. 遍历显示所有自定义字段的数据

在某些场景下，你可能希望动态地列出所有自定义字段及其值，例如在产品详情页中展示一个“详细参数”列表。这时，archiveParams标签就派上用场了。它能获取指定文档的所有额外参数（即自定义字段）。

archiveParams标签会返回一个包含所有自定义字段的数组（默认是排序过的），每个字段都包含Name（参数名，即后台显示的中文名）和Value（参数值，即填入的数据）属性。

{# 假设我们正在一个文档的详情页，需要显示所有自定义字段 #}
<div>
    <h3>详细参数</h3>
    <ul>
        {% archiveParams params %}
            {% for item in params %}
                {# item.Name 是后台设置的“参数名”（中文），item.Value 是填入的数据 #}
                <li>{{ item.Name }}：{{ item.Value }}</li>
            {% endfor %}
        {% endarchiveParams %}
    </ul>
</div>

{# 如果你想排除某些字段不显示，可以结合 if 标签： #}
<div>
    <h3>部分参数</h3>
    <ul>
        {% archiveParams params %}
            {% for item in params %}
                {% if item.Name != '内部备注' and item.Name != '管理员可见' %}
                    <li>{{ item.Name }}：{{ item.Value }}</li>
                {% endif %}
            {% endfor %}
        {% endarchiveParams %}
    </ul>
</div>

自定义字段显示时的特殊考量

  • 富文本或Markdown内容：如果你的自定义字段类型是多行文本，并且你期望它能解析HTML或Markdown语法，你需要使用|safe过滤器。如果该字段在后台开启了Markdown编辑器，还可以配合render=true参数进行渲染。

    {# 假设 'detailed_description' 是一个存储富文本或Markdown的自定义字段 #}
<div>
    <h3>详细描述</h3>
    {# 如果后台Markdown编辑器开启，且希望渲染Markdown #}
    {% archiveDetail detailDesc with name="detailed_description" render=true %}
    {{ detailDesc|safe }}


    {# 如果字段是普通HTML，或者Markdown已在后台处理成HTML #}
    {% archiveDetail plainHtmlDesc with name="detailed_description" %}
    {{ plainHtmlDesc|safe }}
</div>

  • 图片或文件字段：如果你的自定义字段设计用于上传图片（例如产品画廊），其值通常会是一个图片URL字符串，或者是一个图片URL数组。

    {# 假设 'main_image' 是一个单张图片的自定义字段 #}
{% archiveDetail mainImage with name="main_image" %}
{% if mainImage %}<img src="{{ mainImage }}" alt="主图" />{% endif %}


{# 假设 'gallery_images' 是一个多张图片的自定义字段（数组） #}
{% archiveDetail galleryImages with name="gallery_images" %}
{% if galleryImages %}
    <div class="product-gallery">
        {% for imgUrl in galleryImages %}
            <img src="{{ imgUrl }}" alt="画廊图片" />
        {% endfor %}
    </div>
{% endif %}

    这里需要注意，Images 是一个特殊的内置字段，可以像上面那样直接循环。如果你的自定义字段是单个图片上传，它将返回一个字符串路径；如果是多图上传，则可能返回一个字符串数组，具体取决于字段类型与后台实现。

  • 选择/下拉类型字段：这些字段在模板中直接调用item.Value时，会显示用户选择的文本值。无需额外处理。

通过这些灵活的调用方式，安企CMS的