如何使用安企CMS的`archiveDetail`标签显示文档的自定义字段内容？

安企CMS以其灵活的内容模型设计，让用户能够根据自身业务需求，为文档添加各种自定义字段。这些自定义字段极大地丰富了网站内容的表现形式，无论是展示产品规格、活动详情还是文章附加信息，都能得心应手。那么，如何在文档详情页中巧妙地运用archiveDetail标签来展示这些宝贵的自定义字段内容呢？

理解 archiveDetail 标签的核心作用

在安企CMS的模板系统中，archiveDetail标签是用来获取单个文档详细信息的利器。当你在网站**问一篇具体的文章、一个产品页面时，通常就是这个标签在幕后默默工作，将文档的所有数据呈现给访客。

这个标签的基本用法是这样的：{% archiveDetail 变量名称 with name="字段名称" id="1" %}。 其中：

  • name 参数指定你要获取哪个字段的内容，比如文档标题Title、文档内容Content等。
  • id 参数用于指定具体的文档ID，如果你想获取某一特定文档的信息，可以通过这个参数。
  • token 参数是文档的URL别名，也可以用来指定文档。
  • siteId 则是在多站点环境下，用来指定获取哪个站点的数据。

不过，大多数时候，当你在文档详情页（例如，文件名为{模型table}/detail.html的模板中）使用archiveDetail标签时，通常不需要明确指定id或token。系统会智能地识别当前页面的文档，并自动获取其详细数据。此时，你可以直接使用{{archive.字段名称}}这样的简写方式来调用文档的标准字段，方便又直观。然而，对于自定义字段，我们往往会更多地依赖archiveDetail标签的name参数来精确获取。

展示文档的标准字段内容

在深入自定义字段之前，我们先来看看archiveDetail如何展示一些常见的标准字段。这些字段通常在所有文档中都存在，无需额外配置：

比如，要显示文档的标题、描述、内容或浏览量，你可以这样做：

<div>文档标题：{% archiveDetail with name="Title" %}</div>
<div>文档描述：{% archiveDetail with name="Description" %}</div>
<div>文档浏览量：{% archiveDetail with name="Views" %}</div>
<div>文档发布时间：{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</div>
<div>文档内容：{% archiveDetail archiveContent with name="Content" %}{{archiveContent|safe}}</div>

请注意，在展示文档内容（Content）时，我们通常会用到|safe过滤器。这是因为文档内容可能包含HTML标签，|safe告诉模板引擎这段内容是安全的，不需要进行转义，从而确保HTML能够正常渲染，而不是显示为纯文本。

核心功能：显示自定义字段内容

安企CMS的强大之处在于其灵活的内容模型。在后台的“内容管理”菜单下，你可以进入“内容模型”设置，为不同的内容类型（如文章、产品）创建或修改模型，并为它们添加独有的自定义字段。这些自定义字段可以是单行文本、数字、多行文本、单项选择、多项选择或下拉选择等多种类型，旨在满足各种个性化的内容展示需求。

1. 调用单个自定义字段

一旦在后台为文档模型定义了自定义字段，比如你为产品模型添加了一个名为“产品型号”的字段，其调用字段名为product_model，那么在产品详情页中，你就可以通过archiveDetail标签的name参数直接调用它：

<div>产品型号：{% archiveDetail with name="product_model" %}</div>

如果你自定义的字段名叫author，你可以这样获取：

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

这种方法简单直接，适用于你明确知道要显示哪个自定义字段的场景。

2. 循环显示所有自定义字段

有时候，你可能希望在一个区域集中显示某个文档的所有自定义字段，而不需要逐一明确列出。这时，archiveParams标签就派上用场了。archiveParams标签能够获取当前文档或指定文档的所有自定义参数，并以数组形式返回。

你可以这样使用它：

{% archiveParams params %}
<div>
    {% for item in params %}
    <div>
        <span>{{item.Name}}：</span>
        <span>{{item.Value}}</span>
    </div>
    {% endfor %}
</div>
{% endarchiveParams %}

在这段代码中，params是一个包含多个对象的数组，每个对象都有Name（自定义字段的中文名称）和Value（该字段的值）属性。通过for循环，你可以轻松地遍历并展示文档的所有自定义字段。这对于需要动态展示产品参数列表或详细属性的场景尤其方便。

3. 处理特殊自定义字段（如组图）

如果你的自定义字段类型是组图（多张图片），例如你在后台定义了一个名为arcimages的组图字段，那么它在模板中会被识别为一个图片URL的数组。你需要用循环来逐一显示这些图片：

{% archiveDetail arcimages with name="arcimages" %}
<ul class="arc-images">
  {% for img in arcimages %}
  <li><img src="{{img}}" alt="文档图片" /></li>
  {% endfor %}
</ul>

这里，我们首先用archiveDetail标签获取名为arcimages的组图数据并赋值给arcimages变量，然后通过for循环遍历这个数组，将每张图片的URL嵌入到<img>标签中。

实践案例：将标准与自定义字段结合显示

为了更好地说明archiveDetail的实际应用，我们来看看如何在常见的文章和产品详情页中结合标准字段和自定义字段。

文章详情页布局示例：

假设你有一个文章详情页，除了标题、内容、发布时间、浏览量等标准信息，还希望显示“文章来源”（自定义字段source）和“编辑者”（自定义字段editor）。

<article>
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div>
        <a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a>
        <span>发布时间：{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        <span>浏览量：{% archiveDetail with name="Views" %}°</span>
    </div>
    <div>
        <span>文章来源：{% archiveDetail with name="source" %}</span>
        <span>编辑者：{% archiveDetail with name="editor" %}</span>
    </div>
    <div>
        {%- archiveDetail articleContent with name="Content" %}
        {{articleContent|safe}}
    </div>
</article>

产品详情页布局示例：

对于产品详情页，你可能需要显示产品图片、产品名称、产品简介，并用archiveParams来动态展示所有产品规格参数。

<article>
    <div>
        <div>
            <img src="{% archiveDetail with name='Logo' %}" alt="{% archiveDetail with name='Title' %}" />
        </div>
        <div>
            <h1>{% archiveDetail with name="Title" %}</h1>
            <div>产品简介：{% archiveDetail with name="Description" %}</div>
            
            <h3>产品参数：</h3>
            {% archiveParams params %}
            {% for item in params %}
            <div>
                <span>{{item.Name}}：</span>
                <span>{{item.Value}}</span>
            </div>
            {% endfor %}
            {% endarchiveParams %}
            
            <div>
                <a href="tel:{% contact with name='Cellphone' %}" rel="nofollow">电话联系：{% contact with name="Cellphone" %}</a>
            </div>
        </div>
    </div>
    <div>
        <h2>产品详情：</h2>
        <div>
            {%- archiveDetail articleContent with name="Content" %}
            {{articleContent|safe}}
        </div>
    </div>
</article>

使用提示与注意事项

  • |safe 过滤器不可或缺： 当你的自定义字段内容（尤其是“多行文本”类型）可能包含HTML标签时，务必使用|safe过滤器，否则HTML代码会被转义成纯文本，无法正常渲染。
  • Markdown 内容的渲染： 如果你的自定义字段内容是使用Markdown编辑器输入的，并且希望在前端将其渲染为HTML，可以在archiveDetail标签中添加render=true参数，例如 {% archiveDetail customMarkdownField with name="customMarkdown" render=true %}{{customMarkdownField|safe}}。
  • 字段名称严格区分大小写： 在