`archiveDetail`标签如何获取并显示单个文档的完整内容和属性？

在使用安企CMS（AnQiCMS）构建网站内容时，展示单个文档的完整信息是核心需求之一。无论是一篇文章的详细内容、一个产品的详细介绍，还是其他任何自定义内容模型的具体条目，都需要一个高效且灵活的方式来提取和呈现这些数据。这正是 archiveDetail 标签发挥作用的地方。

理解 archiveDetail 标签的核心作用

archiveDetail 标签是安企CMS模板引擎中专门用于获取并展示单个文档（即内容管理后台中的“文档”）所有详细内容和属性的强大工具。它能够帮助我们在文档详情页面上，将标题、正文、图片、自定义参数，甚至相关的分类、标签等信息一并呈现给访问者。

通常情况下，当我们访问一个文档的详情页时，archiveDetail 标签会自动识别当前页面的文档，并获取其所有相关数据。这意味着你无需手动指定文档ID，标签就能智能地工作。

如何指定要获取的文档：id、token 和 siteId 参数

虽然 archiveDetail 默认会获取当前页面上的文档信息，但在某些场景下，我们可能需要获取特定文档的数据，例如在首页展示一个“推荐文章”的完整详情，或者在一个产品页面的侧边栏展示另一个相关产品的完整信息。这时，就可以通过 id 或 token 参数来明确指定目标文档：

  • id：直接通过文档的数字ID来指定。例如，{% archiveDetail with name="Title" id="1" %} 将获取 ID 为 1 的文档标题。
  • token：如果文档设置了 URL 别名（通常用于伪静态URL），可以使用 token 参数来指定。例如，{% archiveDetail with name="Content" token="about-us" %} 可能用于获取别名为 “about-us” 的文档内容。

此外，对于使用安企CMS多站点管理功能的用户，如果需要调用其他站点的数据，可以使用 siteId 参数来指定目标站点。不过在大多数单站点应用中，这个参数通常无需手动填写。

探索文档的丰富属性：通过 name 参数获取

archiveDetail 标签最常用的功能是通过 name 参数来获取文档的各项具体属性。这些属性涵盖了文档的方方面面，从基本的文本内容到多媒体资源，再到时间戳和自定义字段。

你可以直接使用 {% archiveDetail with name="属性名" %} 来直接输出某个属性的值，或者通过 {% archiveDetail 变量名 with name="属性名" %}{{ 变量名 }} 的方式将属性值赋给一个变量，再进行后续操作。

让我们来看一些常用的属性及其应用：

1. 基本信息：标题、描述、内容

  • Title：文档的标题。这是最基础也是最重要的信息之一。
  • Description：文档的简介或描述。常用于详情页的摘要部分。
  • Content：文档的正文内容。这是详情页面的核心。值得注意的是，Content 属性支持两个额外的参数：
    • lazy="data-src"：如果你的模板启用了图片懒加载，可以通过这个参数将 <img> 标签的 src 属性替换为 data-src 或其他指定属性。
    • render=true|false：当你在后台使用 Markdown 编辑器时，Content 默认会自动将 Markdown 格式转换为 HTML。如果你需要手动控制这个转换过程，可以使用 render=false 阻止自动转换，或 render=true 强制转换。

2. 图片资源：Logo、缩略图、多图展示

文档通常会包含图片，用于展示、预览或作为封面：

  • Logo：文档的封面首图。
  • Thumb：文档的封面缩略图。
  • Images：如果文档关联了多张图片（例如产品详情页的轮播图），Images 会返回一个图片URL数组，你可以通过 for 循环来遍历并展示所有图片。

3. 时间信息：发布与更新时间

  • CreatedTime：文档的发布时间戳。
  • UpdatedTime：文档的更新时间戳。

这些时间戳通常需要通过 stampToDate 标签进行格式化，才能以人类可读的日期格式显示，例如：{{ stampToDate(archive.CreatedTime, "2006-01-02 15:04") }}。

4. 关联信息：所属分类与标签

一个文档往往不只孤立存在，它会归属于某个分类，并可能被打上多个标签：

  • Category：获取文档所属分类的完整信息，包括分类ID、标题、链接、描述等。这使得你可以在文档详情页轻松展示其所属分类的名称并提供链接。
  • Tag：文档关联的标签列表。通常需要结合 tagList 标签来遍历展示。

5. 自定义字段：灵活扩展内容

安企CMS的强大之处在于其灵活的内容模型。如果你为某个内容模型定义了额外的自定义字段（例如“作者”、“来源”、“产品参数”等），这些字段也可以通过 archiveDetail 标签获取。

  • 直接通过 name 访问：如果自定义字段的名称是 author，你可以直接使用 {% archiveDetail with name="author" %} 来获取其值。

  • 通过 archiveParams 标签循环：对于数量不确定或需要遍历展示的自定义参数，可以使用 archiveParams 标签。它可以返回一个包含所有自定义字段名称和值的数组，便于你统一展示，例如：

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

实际应用场景示例

archiveDetail 标签的灵活性使其能够适应各种复杂的页面展示需求。

1. 构建标准文章详情页

在一个典型的文章详情页中，你会希望展示文章标题、发布时间、所属分类、浏览量、标签和文章内容。

<article>
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div class="meta-info">
        <span>分类：<a href="{% categoryDetail with name='Link' %}">{% categoryDetail with name='Title' %}</a></span>
        <span>发布日期：{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        <span>浏览量：{% archiveDetail with name="Views" %}</span>
        <div class="tags">
            标签：{% tagList tags %}{% for tag in tags %}<a href="{{ tag.Link }}">{{ tag.Title }}</a> {% endfor %}{% endtagList %}
        </div>
    </div>
    <div class="content">
        {%- archiveDetail articleContent with name="Content" render=true lazy="data-src" %}
        {{ articleContent|safe }} {# 注意：使用 |safe 过滤器确保HTML内容正确渲染 #}
    </div>
</article>

2. 展示产品详细信息

对于一个产品详情页，除了产品名称和描述，可能还需要展示多个产品图片、价格和自定义的产品参数。

<section class="product-detail">
    <div class="product-gallery">
        {% archiveDetail productImages with name="Images" %}
        {% for img in productImages %}
            <img src="{{ img }}" alt="{% archiveDetail with name='Title' %}" />
        {% endfor %}
        {% endarchiveDetail %}
    </div>
    <div class="product-info">
        <h1>{% archiveDetail with name="Title" %}</h1>
        <p class="price">价格：{% archiveDetail with name="Price" %}</p>
        <p class="description">{% archiveDetail with name="Description" %}</p>
        <div class="parameters">
            {% archiveParams params %}
            {% for param in params %}
                <div>{{ param.Name }}：{{ param.Value }}</div>
            {% endfor %}
            {% endarchiveParams %}
        </div>
    </div>
    <div class="full-description">
        <h2>产品详情</h2>
        {%- archiveDetail productContent with name="Content" render=true %}
        {{ productContent|safe }}
    </div>
</section>

使用 archiveDetail 的实用技巧

  • 善用 |safe 过滤器：当 archiveDetail 获取到的是可能包含 HTML 标签的内容（如 Content 或 Description），一定要使用 |safe 过滤器，以避免内容被转义，确保 HTML 结构能正确渲染。
  • 结合其他标签：archiveDetail 经常与其他标签协同工作。例如，使用 prevArchive 和 nextArchive 标签来创建上一篇/下一篇导航，或结合 archiveList 来显示相关文档。
  • 变量命名：为了提高模板的可读性，建议为 archiveDetail 获取到的值赋予有意义的变量名，例如 {% archiveDetail articleTitle with name="Title" %}。

掌握了 archiveDetail 标签的用法，你就能在安企CMS中更加自如地构建出内容丰富、动态多变的详情页面，为用户提供更优质的浏览体验。

常见问题 (FAQ)

Q1: 为什么我在 archiveDetail 中获取到的 Content 内容没有正确显示为 HTML，而是显示了原始的 Markdown 文本或带有 <p> 标签？ A1: 如果你使用的是 Markdown 编辑器，确保在 archiveDetail 标签中添加 render=true 参数，例如 {% archiveDetail articleContent with name="Content" render=true %}{{ articleContent|safe }}。同时，务必在输出内容的变量后加上 |safe 过滤器，以防止 HTML 标签被转义。

Q2: 我想展示文档的发布时间，但直接输出 CreatedTime 得到的是一串数字，如何将其格式化为日期格式？ A2: CreatedTime 和 UpdatedTime 返回的是时间戳。你需要使用 stampToDate 标签来格式化它。例如，要显示为“2006-01-02”，可以使用 {{ stampToDate(archive.CreatedTime, "2006-01-02") }}。安企CMS支持Go语言的时间格式化规则，可以根据需要调整格式字符串。

Q3: 如何在文档详情页获取其所属分类的图片和描述？ A3: archiveDetail 标签的 name="Category" 参数可以直接获取文档所属分类的完整对象。然后你可以通过这个分类对象进一步获取其属性。例如：

{% archiveDetail docCategory with name="Category" %}
    <img src="{{ docCategory.Logo }}" alt="{{ docCategory.Title }}" />
    <p>{{ docCategory.Description }}</p>
{% endarchiveDetail %}

或者，你也可以结合 categoryDetail 标签，通过 archiveDetail 获取到的 CategoryId 来指定：

{% categoryDetail catLogo with name="Logo" id=archive.CategoryId %}
<img src="{{ catLogo }}" />