如何在 AnQiCMS 模板中获取当前文档的详细信息（如标题、内容、缩略图）？

作为一名资深的AnQiCMS网站运营人员，我深知在模板中灵活获取和展示内容的重要性。AnQiCMS强大的模板引擎使得内容的创作、编辑和发布变得高效而便捷。今天，我们将深入探讨如何在AnQiCMS的模板中获取当前文档的详细信息，例如标题、内容和缩略图，从而帮助您更好地定制网站前端展示。

理解AnQiCMS模板中的文档数据

AnQiCMS的模板系统设计得非常直观，尤其是在处理文档（archive）这类核心内容时。当您访问一个文档详情页时，系统会自动将当前文档的所有可用信息加载到模板的上下文中。这意味着您可以使用特定的标签和变量，轻松地访问这些数据。核心在于archiveDetail标签，它是获取单个文档详细信息的主要工具。

使用archiveDetail标签获取文档信息

archiveDetail标签是AnQiCMS提供的一个强大且灵活的标签，用于获取指定或当前文档的各项字段值。它的基本用法是{% archiveDetail 变量名称 with name="字段名称" %}。您也可以选择不定义变量名称，直接让标签输出结果。

获取文档标题

文档标题是任何内容的核心标识。在AnQiCMS模板中获取当前文档的标题非常简单。您可以使用archiveDetail标签并指定name="Title"来获取它。

例如，在您的文档详情页模板中，可以直接这样放置代码：

<h1>{% archiveDetail with name="Title" %}</h1>

如果希望将标题赋值给一个变量以便后续处理，可以这样操作：

{% archiveDetail currentTitle with name="Title" %}
<h1>{{ currentTitle }}</h1>

此外，如果您需要获取指定ID文档的标题，可以在标签中添加id参数：

<p>ID为1的文档标题是：{% archiveDetail with name="Title" id="1" %}</p>

获取文档内容

文档内容是页面的主体信息，可能包含丰富的文本、图片和嵌入媒体。archiveDetail标签同样能够轻松地提取这部分数据，通过指定name="Content"来实现。由于文档内容通常包含HTML标签，为了确保这些标签能被浏览器正确解析并显示样式，我们通常会配合|safe过滤器使用。

以下是获取文档内容的基本方式：

<div class="article-content">
    {% archiveDetail with name="Content" %}
</div>

请注意，为了安全起见，AnQiCMS模板引擎默认会对所有输出的变量进行HTML转义，以防止跨站脚本攻击（XSS）。这意味着如果您的文档内容包含HTML标签，它们将以纯文本形式显示。如果您确定内容是安全的，并且需要浏览器解析其中的HTML，务必使用|safe过滤器：

<div class="article-content">
    {% archiveDetail articleContent with name="Content" %}
    {{ articleContent|safe }}
</div>

AnQiCMS还支持Markdown编辑器。如果文档内容是用Markdown编写的，并且您希望在前端自动渲染成HTML，可以在archiveDetail标签中添加render=true参数。同时，如果您的网站使用了图片懒加载功能，并需要将图片src属性替换为data-src或类似属性，可以使用lazy="data-src"参数，标签会自动处理。

{# 假设文档内容为Markdown，并希望自动渲染成HTML #}
<div class="article-content markdown-body">
    {% archiveDetail renderedContent with name="Content" render=true %}
    {{ renderedContent|safe }}
</div>

{# 同时启用Markdown渲染和图片懒加载 #}
<div class="article-content markdown-body">
    {% archiveDetail lazyRenderedContent with name="Content" render=true lazy="data-src" %}
    {{ lazyRenderedContent|safe }}
</div>

获取文档缩略图

文档缩略图在列表页、相关推荐或文章详情页顶部横幅等场景中都扮演着重要角色。AnQiCMS为文档提供了几种不同类型的图片字段，最常用的是Logo（通常指封面首图或大图）和Thumb（通常指经过裁剪或处理的缩略图）。您可以通过指定对应的name参数来获取它们。

获取文档封面首图（Logo）：

<div class="article-image">
    <img src="{% archiveDetail with name="Logo" %}" alt="{% archiveDetail with name="Title" %}" />
</div>

获取文档封面缩略图（Thumb）：

<div class="article-thumbnail">
    <img src="{% archiveDetail with name="Thumb" %}" alt="{% archiveDetail with name="Title" %}" />
</div>

在实际应用中，您可能会将这些图片用于响应式设计，或者根据页面的不同区域选择性地展示。

获取其他常用文档信息

除了标题、内容和缩略图，文档还包含许多其他有用的信息，您同样可以使用archiveDetail标签来获取它们。

• 文档ID：{% archiveDetail with name="Id" %}
• 文档链接：{% archiveDetail with name="Link" %}
• 文档描述：{% archiveDetail with name="Description" %}
• 文档分类ID：{% archiveDetail with name="CategoryId" %}
• 文档浏览量：{% archiveDetail with name="Views" %}
• 文档创建时间：{% archiveDetail with name="CreatedTime" %}。由于CreatedTime返回的是时间戳，您需要使用stampToDate过滤器将其格式化为可读的日期和时间，例如{{ stampToDate(archive.CreatedTime, "2006-01-02 15:04") }}。
• 文档更新时间：{% archiveDetail with name="UpdatedTime" %}，同样需要使用stampToDate进行格式化。

AnQiCMS还支持自定义内容模型字段。如果您在后台为特定模型添加了自定义字段，例如author或product_sku，您也可以直接通过archiveDetail标签来获取它们的值：

<p>作者：{% archiveDetail with name="author" %}</p>
<p>产品SKU：{% archiveDetail with name="product_sku" %}</p>

甚至，如果您需要循环显示所有自定义字段，可以使用archiveParams标签：

{% archiveParams params %}
<div class="custom-fields">
    {% for item in params %}
    <p><strong>{{ item.Name }}：</strong> {{ item.Value }}</p>
    {% endfor %}
</div>
{% endarchiveParams %}

实践案例：构建一个完整的文档详情页片段

综合上述内容，我们可以构建一个更完整的文档详情页片段，来展示如何有效利用这些标签获取和展示当前文档的详细信息：

<article class="document-detail">
    {# 获取文档标题 #}
    <h1>{% archiveDetail with name="Title" %}</h1>

    <div class="article-meta">
        {# 获取分类信息 #}
        {% archiveDetail articleCategory with name="Category" %}
        <span class="category">分类：<a href="{{ articleCategory.Link }}">{{ articleCategory.Title }}</a></span>
        
        {# 获取创建时间并格式化 #}
        {% archiveDetail createdTime with name="CreatedTime" %}
        <span class="publish-date">发布时间：{{ stampToDate(createdTime, "2006年01月02日 15:04") }}</span>
        
        {# 获取浏览量 #}
        <span class="views">浏览量：{% archiveDetail with name="Views" %}</span>
    </div>

    {# 获取文档封面大图，并假设alt文本为标题 #}
    {% archiveDetail coverLogo with name="Logo" %}
    {% if coverLogo %}
    <div class="article-cover">
        <img src="{{ coverLogo }}" alt="{% archiveDetail with name="Title" %}" />
    </div>
    {% endif %}

    {# 获取文档内容，启用Markdown渲染和图片懒加载 #}
    <div class="article-content markdown-body">
        {% archiveDetail articleContent with name="Content" render=true lazy="data-src" %}
        {{ articleContent|safe }}
    </div>

    {# 获取文档描述 #}
    {% archiveDetail description with name="Description" %}
    {% if description %}
    <div class="article-description">
        <p><strong>简介：</strong>{{ description }}</p>
    </div>
    {% endif %}

    {# 获取并显示自定义字段（假设有一个名为"来源"的字段） #}
    {% archiveDetail source with name="来源" %}
    {% if source %}
    <p class="article-source">来源：{{ source }}</p>
    {% endif %}

    {# 获取并显示文档标签 #}
    <div class="article-tags">
        <strong>标签：</strong>
        {% tagList tags %}
        {% for tagItem in tags %}
        <a href="{{ tagItem.Link }}">{{ tagItem.Title }}</a>{% if not forloop.Last %}, {% endif %}
        {% endfor %}
        {% endtagList %}
    </div>
</article>

总结

在AnQiCMS模板中获取当前文档的详细信息是一项基础且关键的操作。通过熟练运用archiveDetail标签，您可以精确地提取文档的标题、内容、缩略图以及各种自定义字段。结合|safe过滤器、render参数进行Markdown内容处理，以及stampToDate函数进行时间格式化，您将能够打造出功能丰富、展示优雅的网站页面。记住，在处理用户生成内容时，始终对使用|safe过滤器保持警惕，确保内容的安全性。

常见问题解答 (FAQ)

为什么我在模板中使用了archiveDetail标签，但没有显示任何内容？

可能的原因有几个。首先，请确保您当前访问的是一个文档详情页，因为archiveDetail标签默认会尝试获取当前页面的文档信息。如果您在非文档详情页（如列表页或首页）使用此标签而未指定id或token参数，它将无法找到对应的文档。其次，检查您name参数中指定的字段名称是否正确，包括大小写是否匹配，例如Title而不是title。最后，如果您尝试获取的是自定义字段，请确认该字段已在后台内容模型中正确配置，并且当前文档确实填写了该字段的值。

在显示文档内容时，我使用了|safe过滤器，但仍担心存在安全风险，有什么建议吗？

|safe过滤器用于指示模板引擎将输出内容视为安全的HTML，不再进行转义。虽然它在显示富文本内容时必不可少，但确实引入了潜在的XSS风险，尤其是在内容由不受信任的用户输入时。建议您在后台对用户提交的内容进行严格的清洗和过滤，移除恶意脚本或不安全的HTML标签，以最大限度地降低风险。如果可能，对于用户提交的纯文本或Markdown内容，尽量避免直接使用|safe，而是依赖系统自带的Markdown渲染功能（render=true），这通常会更安全。

我如何获取当前文档所属分类的详细信息（例如分类名称、分类链接）？

当前文档所属分类的ID可以通过{% archiveDetail with name="CategoryId" %}获取。获得分类ID后，您可以进一步使用categoryDetail标签来获取该分类的详细信息。例如：

{% archiveDetail currentCategoryId with name="CategoryId" %}
{% categoryDetail categoryInfo with id=currentCategoryId %}
<p>分类名称：<a href="{{ categoryInfo.Link }}">{{ categoryInfo.Title }}</a></p>

或者，archiveDetail标签本身也提供了Category字段，可以直接获取分类对象，更加简洁：

{% archiveDetail archiveCategory with name="Category" %}
<p>分类名称：<a href="{{ archiveCategory.Link }}">{{ archiveCategory.Title }}</a></p>