如何在AnQiCMS模板中调用文档详情数据（archiveDetail）？
作为一名资深的安企CMS网站运营人员，我深知内容是网站的核心，而如何高效、精准地展示这些内容，则是我们日常工作中关注的重点。今天，我们将深入探讨AnQiCMS模板中一个至关重要的标签——archiveDetail，它能帮助我们灵活地调用和展示文档的详细数据。
理解 archiveDetail 标签的核心作用
在AnQiCMS中，无论是文章、产品还是其他自定义模型的内容，我们都统称为“文档”（archive）。archiveDetail标签的核心功能，正是用于在模板中获取并展示单个文档的详细信息。它允许我们精确地指定要获取哪个文档的哪些字段数据，从而满足各种内容展示的需求。
通常情况下，当我们访问一个文档的详情页面时，AnQiCMS会自动识别当前页面的文档ID，此时我们无需额外指定ID，archiveDetail便能直接获取到当前文档的数据。然而，在某些需要展示特定文档数据（例如在侧边栏推荐文章、或者在产品页面展示关联文章）的场景下，我们就需要通过参数来明确指定文档。
archiveDetail 的基本用法与参数解析
archiveDetail标签的使用方式非常直观，其基础语法结构为：
{% archiveDetail [变量名称] with name="字段名称" [id="文档ID"] [token="文档URL别名"] [siteId="站点ID"] %}
让我们来详细解读这些参数：
name="字段名称"：这是最关键的参数，用于指定您希望从文档中获取的具体字段。例如，name="Title"会获取文档标题，name="Content"会获取文档内容。id="文档ID"：如果您想获取的不是当前页面正在展示的文档，而是网站中特定ID的文档，可以通过这个参数来指定。例如，id="10"会获取ID为10的文档数据。token="文档URL别名"：与id类似，您也可以通过文档的URL别名（通常是伪静态链接中的唯一标识）来指定文档。siteId="站点ID"：在多站点管理的环境下，如果您需要调用其他站点的文档数据，可以通过此参数指定站点ID。一般情况下，无需填写此参数，系统会默认获取当前站点的数据。[变量名称]：这是一个可选参数。如果您希望将获取到的文档数据赋值给一个变量，以便在模板中进行更复杂的处理（例如条件判断、循环或者多个字段的组合显示），就可以在此处定义一个变量名。如果不指定变量名，标签会直接输出其name参数指定的值。
常用字段的调用示例
archiveDetail标签可以获取文档的多种内置字段。以下是一些我们运营人员最常使用的字段及其调用方式：
文档标题 (Title)
这是任何内容页面的核心。通过name="Title"，您可以轻松展示文档的标题。
{# 直接输出当前文档标题 #}
<h1>{% archiveDetail with name="Title" %}</h1>
{# 获取ID为5的文档标题并赋值给变量 #}
{% archiveDetail myDocTitle with name="Title" id="5" %}
<p>相关文章：{{ myDocTitle }}</p>
文档内容 (Content)
文档内容是页面主体，Content字段还支持两个重要的属性：
lazy="data-src"：如果您使用了图片懒加载插件，可以通过此属性将<img>标签的src属性替换为data-src等，以优化页面加载性能。render=true|false：当内容包含Markdown格式时，设置为render=true可以自动将其转换为HTML。如果您的内容已经是纯HTML或不需要转换，可以设置为render=false。
{# 直接输出当前文档内容，并支持图片懒加载和Markdown渲染 #}
<div class="article-content">
{% archiveDetail with name="Content" lazy="data-src" render=true %}
</div>
{# 获取特定文档内容并赋值，不进行Markdown渲染 #}
{% archiveDetail articleBody with name="Content" id="12" render=false %}
<div class="excerpt">{{ articleBody|safe }}</div>
请注意，当输出内容包含HTML标签时，通常需要加上|safe过滤器，以防止HTML被转义而无法正常显示。
文档链接 (Link)
获取文档的URL链接，常用于构建导航或相关推荐。
<a href="{% archiveDetail with name="Link" %}">阅读更多</a>
文档创建时间 (CreatedTime) 与更新时间 (UpdatedTime)
这些字段返回的是时间戳，需要配合format参数进行格式化显示。AnQiCMS的时间格式化遵循Go语言的规则，例如"2006-01-02"表示年月日。
<p>发布时间：{% archiveDetail with name="CreatedTime" format="2006年01月02日 15:04" %}</p>
<p>最近更新：{% archiveDetail with name="UpdatedTime" format="2006-01-02" %}</p>
文档封面图 (Logo / Thumb) 与多图 (Images)
Logo：通常用于获取文档的主图或大图。Thumb：用于获取文档的缩略图，适用于列表展示。Images：如果文档包含一组图片（例如产品详情的轮播图），则此字段会返回一个图片URL数组。
{# 显示文档主图 #}
<img src="{% archiveDetail with name="Logo" %}" alt="{% archiveDetail with name="Title" %}">
{# 循环显示一组图片 #}
{% archiveDetail galleryImages with name="Images" %}
{% if galleryImages %}
<div class="product-carousel">
{% for imgUrl in galleryImages %}
<img src="{{ imgUrl }}" alt="图片">
{% endfor %}
</div>
{% endif %}
文档分类 (Category)
获取文档所属的分类信息。此字段会返回一个包含分类ID、标题、链接等属性的对象。
{% archiveDetail docCategory with name="Category" %}
<p>分类：<a href="{{ docCategory.Link }}">{{ docCategory.Title }}</a></p>
文档自定义字段
AnQiCMS的内容模型允许我们添加自定义字段，例如“作者”、“来源”或“产品参数”。这些自定义字段可以直接通过其在后台定义的“调用字段”名称作为name参数来获取。
假设您有一个自定义字段，调用字段名为author：
<p>作者：{% archiveDetail with name="author" %}</p>
如果您想展示所有自定义字段，特别是那些不固定的字段，可以使用archiveParams标签来循环显示。
{# 在文档详情页，循环显示所有自定义参数 #}
{% archiveParams customFields %}
{% for param in customFields %}
<p>{{ param.Name }}：{{ param.Value }}</p>
{% endfor %}
{% endarchiveParams %}
结合实际场景的应用
假设我们需要在一个产品详情页，除了展示产品本身的详细信息外，还在侧边栏推荐一篇相关的“使用教程”文章。
{# 产品名称 #}
<h1>{% archiveDetail with name="Title" %}</h1>
{# 产品描述 #}
<div class="product-description">
{% archiveDetail with name="Description" %}
</div>
{# 产品主图 #}
<div class="product-image">
<img src="{% archiveDetail with name="Logo" %}" alt="{% archiveDetail with name="Title" %}">
</div>
{# 产品参数（假设自定义字段名为 "parameters"） #}
<div class="product-specs">
<h2>产品参数</h2>
{% archiveDetail productParams with name="parameters" %}
{# 假设parameters字段存储的是JSON字符串或简单文本 #}
<p>{{ productParams }}</p>
</div>
{# 侧边栏推荐文章：假设我们知道“使用教程”文章的ID是20 #}
<div class="sidebar">
<h3>相关教程</h3>
{% archiveDetail tutorialArticle with name="Title" id="20" %}
{% archiveDetail tutorialLink with name="Link" id="20" %}
<a href="{{ tutorialLink }}">{{ tutorialArticle }}</a>
</div>
通过archiveDetail标签的灵活运用，我们可以精确控制每个页面所展示的内容，实现高度定制化的前端展现效果，从而更好地吸引和保留用户。掌握这个标签，是您在AnQiCMS上进行高效内容运营的关键一步。
常见问题解答 (FAQ)
问：我如何在模板中获取到当前文档的所有信息，而不仅仅是单个字段？
答：archiveDetail标签主要用于获取单个字段的值。如果您希望获取当前文档的整个数据对象，并将其赋值给一个变量，以便在模板中更灵活地使用其多个属性（例如{{archive.Title}}、{{archive.Link}}等），您通常不需要显式使用archiveDetail标签来获取全部。在文档详情页的上下文环境中，系统通常会将当前文档的完整数据自动暴露为一个名为archive（或类似名称，具体取决于模板结构）的全局变量。您可以直接通过{{ archive.字段名 }}的方式来访问其属性。如果确实需要通过archiveDetail来获取整个对象，这通常需要将name参数留空，并将整个数据赋值给一个变量，但这种用法在实际操作中较少直接用于获取“所有”字段，更多是系统内部传递机制。
问：我的文档内容是Markdown格式的，但前端显示的是原始Markdown文本，如何才能正确渲染成HTML？
答：当您使用archiveDetail标签调用name="Content"时，可以增加render=true参数来指示系统将Markdown内容转换为HTML。例如：{% archiveDetail with name="Content" render=true %}。同时，为了确保转换后的HTML能够被浏览器正确解析而不是作为纯文本显示，您通常还需要在输出时加上|safe过滤器，例如{{ archiveContent|safe }}。
问：我创建了自定义内容模型并添加了自定义字段，如何在模板中调用这些自定义字段的值？
答：调用自定义字段非常简单。在您使用archiveDetail标签时，将name参数设置为您在后台自定义字段时填写的“调用字段”名称即可。例如，如果您有一个自定义字段的调用字段名为product_code，则可以使用{% archiveDetail with name="product_code" %}来获取其值。如果您想遍历所有自定义字段，可以使用archiveParams标签，它会返回一个包含所有自定义参数的数组，方便您循环展示。