`archiveDetail`标签如何获取指定文档的详细信息，包括自定义字段？
在安企CMS的日常运营中，获取和展示网站内容的详细信息是核心工作之一。archiveDetail 标签是安企CMS模板系统中专门用于此目的的强大工具，它允许我们灵活地提取任何指定文档的详细数据，包括标准的文档属性以及用户自定义的字段内容。
深入理解 archiveDetail 标签的核心功能
archiveDetail 标签在安企CMS模板中扮演着至关重要的角色，它能够帮助网站运营者在页面上展示单个文档的所有相关信息。无论您是想在文章详情页加载当前文章的内容，还是想在其他页面中调用特定文档的数据，archiveDetail 都能提供简洁高效的解决方案。
这个标签的基本用法通常是 {% archiveDetail with name="字段名称" %}。如果标签不指定变量名，它会直接输出所请求字段的值。当您需要将获取到的文档数据存储到一个变量中以供后续复杂的处理或条件判断时，可以这样使用：{% archiveDetail archiveItem with name="字段名称" %}，然后通过 {{ archiveItem }} 来引用该变量。
为了获取特定文档的详细信息，archiveDetail 标签支持以下参数：
id: 通过文档的唯一数字ID来指定要获取的文档。例如，id="1"将获取ID为1的文档。如果未指定此参数，标签会默认尝试获取当前页面所关联的文档。token: 通过文档的URL别名（也称为URL Token）来指定文档。这在URL结构基于别名的情况下非常有用。例如，token="my-article-slug"。与id类似，如果未指定，则默认获取当前文档。siteId: 在安企CMS的多站点管理场景下，如果您需要从其他站点调用文档数据，可以通过此参数指定站点的ID。通常情况下，此参数无需填写，系统会自动识别当前站点。
访问文档的标准字段内容
archiveDetail 标签能够直接获取文档的多种内置标准字段。这些字段涵盖了文档标题、内容、链接、图片等基础信息。以下是一些常用标准字段及其调用示例：
- 文档标题 (
Title):{% archiveDetail with name="Title" %}。这会直接显示文档的标题。 - 文档链接 (
Link):{% archiveDetail with name="Link" %}。用于生成指向该文档详情页的URL。 - 文档描述 (
Description):{% archiveDetail with name="Description" %}。通常用于显示文档的摘要或简介。 - 文档内容 (
Content):{% archiveDetail with name="Content" %}。这是文档的核心文本内容。在使用此字段时，请注意Content支持lazy参数用于图片懒加载，例如lazy="data-src"。此外，如果启用了Markdown编辑器，Content内容会自动转换为HTML；您也可以通过render=true或render=false参数手动控制是否进行Markdown到HTML的转换。为了安全地显示HTML内容，通常需要结合|safe过滤器使用，如{{ articleContent|safe }}。 - 文档封面首图 (
Logo) 和缩略图 (Thumb):{% archiveDetail with name="Logo" %}或{% archiveDetail with name="Thumb" %}。它们分别获取文档的大图和缩略图，常用于在列表中展示或作为页面主视觉元素。 - 文档添加时间 (
CreatedTime):{% archiveDetail with name="CreatedTime" format="2006-01-02 15:04" %}。这个字段返回时间戳，需要通过format参数指定输出的日期时间格式。
例如，在文档详情页中展示文档标题和内容的基本结构可以这样实现：
<article>
<h1>{% archiveDetail with name="Title" %}</h1>
<div class="article-meta">
<span>发布时间：{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
<span>浏览量：{% archiveDetail with name="Views" %}</span>
</div>
<div class="article-content">
{% archiveDetail articleContent with name="Content" lazy="data-src" render=true %}
{{ articleContent|safe }}
</div>
</article>
灵活获取自定义字段内容
安企CMS的一大优势在于其灵活的内容模型，允许运营者为不同类型的内容（如文章、产品）定义独有的自定义字段。例如，为“产品”模型添加“颜色”、“尺寸”、“材质”等字段。archiveDetail 标签同样能够获取这些自定义字段的内容。
要获取一个特定的自定义字段，例如您在后台定义了一个名为 author 的自定义字段，可以直接通过 name 参数来调用：
<p>文章作者：{% archiveDetail with name="author" %}</p>
这种方法适用于您确切知道要调用哪个自定义字段的情况。
当您希望动态地遍历并显示文档所有自定义字段时，可以结合使用 archiveParams 标签。archiveParams 标签能够获取当前文档或指定文档的所有自定义参数，并将其组织成一个可迭代的数组对象。
以下是一个展示所有自定义字段的示例：
{% archiveParams params %}
<div class="custom-fields">
{% for item in params %}
<p>
<strong>{{ item.Name }}：</strong>
<span>{{ item.Value }}</span>
</p>
{% endfor %}
</div>
{% endarchiveParams %}
在上述代码中，params 是通过 archiveParams 标签获取到的自定义字段集合。每个 item 包含 Name（字段显示名称）和 Value（字段值）。如果您的自定义字段存储的是图片路径，例如一个名为 product_gallery 的自定义字段用于存储产品组图，您可以这样遍历并显示图片：
{% archiveDetail productGallery with name="product_gallery" %}
{% if productGallery %}
<div class="product-images">
{% for image in productGallery %}
<img src="{{ image }}" alt="产品图片">
{% endfor %}
</div>
{% endif %}
这里假设 product_gallery 自定义字段的类型是“多图上传”或“多行文本”并存储了多个图片URL。在实际应用中，自定义字段的类型会影响其值的表现形式，因此在模板中需要根据实际情况进行处理。
通过 archiveDetail 和 archiveParams 标签，安企CMS为网站运营者提供了强大的内容展示能力，无论是标准的文档信息还是为特定业务需求定制的字段，都能被精确地获取和渲染，极大地提升了网站的灵活性和可定制性。
常见问题解答 (FAQ)
1. archiveDetail 标签在文档列表页能否获取到指定文档的详细信息？
是的，archiveDetail 标签可以在任何页面上获取指定文档的详细信息。您只需要通过 id 或 token 参数明确指定要获取的文档即可。例如，{% archiveDetail with name="Title" id="10" %} 可以在列表页获取ID为10的文档标题，而不会影响当前列表的循环。
2. 为什么我使用 {% archiveDetail with name="Content" %} 获取到的内容没有正确显示HTML样式或Markdown转换失败？
Content 字段获取的通常是原始文本或包含HTML标签的字符串。如果内容中包含HTML，您需要使用 |safe 过滤器来指示模板引擎不要对其进行转义，例如 {{ archiveContent|safe }}。如果内容是Markdown格式，并期望自动转换为HTML，请确保在后台内容设置中已启用Markdown编辑器，或者在标签中显式添加 render=true 参数。
3. 如何判断一个自定义字段是否存在或有值，以避免页面显示空内容？
当您将自定义字段的值赋给一个变量时，可以使用 if 逻辑判断标签来检查该变量是否存在或是否为空。例如，如果您有一个自定义字段 product_dimensions：
{% archiveDetail dimensions with name="product_dimensions" %}
{% if dimensions %}
<p>产品尺寸：{{ dimensions }}</p>
{% endif %}
这样可以确保只有当字段有值时才显示相关内容。