AnQiCMS模板中如何使用`archiveDetail`标签获取文档详情及自定义字段？

作为一名资深的安企CMS网站运营人员，我深知内容在网站运营中的核心地位。我们不仅要创造优质内容，更要确保这些内容能够以**方式呈现在用户面前。这其中，模板的灵活运用至关重要。今天，我们将深入探讨AnQiCMS模板中一个强大且常用的标签——archiveDetail，它能帮助我们轻松获取文档的详细信息，包括那些精心设计的自定义字段。

理解archiveDetail标签的核心作用

在AnQiCMS中，archiveDetail标签是用于在模板中获取特定文档（如文章、产品等）所有详细数据的重要工具。无论是显示当前页面的文档内容，还是根据需要获取其他指定文档的数据，archiveDetail都能提供所需的一切。它默认会获取当前正在访问的文档信息，但通过简单的参数设置，我们也能够精准地抓取到网站中任意文档的数据。

该标签的基本用法通常包括指定一个变量名称来存储获取到的数据，并使用name参数来指明需要获取的具体字段。如果未指定变量名称，标签将直接输出请求的字段值。

archiveDetail标签的常用参数

archiveDetail标签的灵活性体现在其支持的参数上。除了默认获取当前文档外，它还允许通过以下参数精确控制数据来源：

  • 文档 ID (id)：这是一个可选参数，用于获取指定ID的文档详情。当您需要展示非当前页面的文档数据时，例如在侧边栏推荐文章，就可以用到这个参数。
  • 文档 URL 别名 (token)：与id类似，token也用于指定文档。如果您更熟悉文档的URL别名（通常是拼音或自定义的短链接），可以使用此参数。
  • 站点 ID (siteId)：对于使用AnQiCMS多站点管理功能的用户，siteId可以帮助您跨站点调用数据。如果您的网站是单站点架构，通常无需设置此参数。

这些参数的巧妙组合，让archiveDetail能够适应各种复杂的模板需求。

获取文档的标准字段信息

archiveDetail标签能够返回文档的多种标准字段，这些字段覆盖了文档的基础属性、SEO信息以及媒体内容等。以下是一些常见的可用字段及其使用示例：

  • 文档 ID (Id)、标题 (Title)、链接 (Link)、描述 (Description)：这些是最基础也是最常用的信息。

    {# 获取当前文档的标题 #}
<h1>{% archiveDetail with name="Title" %}</h1>
{# 获取指定ID文档的链接 #}
<a href="{% archiveDetail with name="Link" id="10" %}">查看详情</a>
{# 将文档描述赋值给变量并使用 #}
{% archiveDetail docDesc with name="Description" %}<meta name="description" content="{{docDesc}}">

  • 文档内容 (Content)：这是文档的主体内容。值得注意的是，Content字段支持额外的属性来处理图片懒加载和Markdown渲染。

    • 图片懒加载 (lazy)：如果您的网站使用了懒加载插件，可以通过lazy="data-src"等方式将img标签的src属性替换为插件所需的属性。
    • Markdown 渲染 (render)：当后台启用了Markdown编辑器时，内容会自动渲染。您也可以通过render=true或render=false手动控制是否进行Markdown到HTML的转换。
    {# 获取当前文档内容，并处理图片懒加载和Markdown渲染 #}
{% archiveDetail docContent with name="Content" lazy="data-src" render=true %}{{docContent|safe}}
{# `|safe`过滤器用于避免HTML实体转义，确保内容正确显示 #}

  • 浏览量 (Views)、评论数量 (CommentCount)：用于展示文档的互动数据。

    <span>浏览量：{% archiveDetail with name="Views" %}次</span>

  • 封面图片 (Logo、Thumb、Images)：Logo通常指大图，Thumb指缩略图，而Images则可能是一个图片数组，用于展示组图。

    {# 获取文档Logo #}
<img src="{% archiveDetail with name="Logo" %}" alt="{% archiveDetail with name="Title" %}">
{# 循环输出文档组图 #}
{% archiveDetail docImages with name="Images" %}
<ul>
{% for img in docImages %}
    <li><img src="{{img}}"></li>
{% endfor %}
</ul>

  • 创建时间 (CreatedTime)、更新时间 (UpdatedTime)：这些字段返回时间戳，需要配合format参数或stampToDate过滤器进行格式化。

    <span>发布日期：{% archiveDetail with name="CreatedTime" format="2006-01-02 15:04" %}</span>
{# 或者使用变量和过滤器 #}
{% archiveDetail createdTime with name="CreatedTime" %}{{stampToDate(createdTime, "2006年01月02日")}}

  • 文档分类 (Category)：此字段返回一个包含分类信息的对象。您可以直接访问其属性，也可以考虑使用categoryDetail标签获取更全面的分类信息。

    {% archiveDetail docCategory with name="Category" %}
<p>所属分类：<a href="{{docCategory.Link}}">{{docCategory.Title}}</a></p>

  • 文档标签（Tag）：虽然archiveDetail本身不直接返回标签列表，但您可以在获取文档ID后，结合tagList标签来获取相关标签。

    {% archiveDetail currentDocId with name="Id" %}
{% tagList tags with itemId=currentDocId %}
{% for tag in tags %}
    <a href="{{tag.Link}}">{{tag.Title}}</a>
{% endfor %}
{% endtagList %}

获取文档的自定义字段信息

AnQiCMS强大的灵活内容模型允许我们为不同类型的文档定义专属的自定义字段。这些自定义字段同样可以通过archiveDetail标签来获取，这极大地增强了模板的定制能力。

如果您明确知道自定义字段的名称（例如，您在内容模型中定义了一个名为author的字段），可以直接通过name参数进行调用：

{# 获取自定义字段“author”的值 #}
<p>作者：{% archiveDetail with name="author" %}</p>

更进一步，如果您需要遍历所有自定义字段，或者不确定所有字段的具体名称，可以使用archiveParams标签。它会将所有自定义字段作为数组对象返回，方便您进行循环展示：

{% archiveParams params %}
<div>
    {% for item in params %}
    <p>
        <span>{{item.Name}}：</span> {# 字段的显示名称 #}
        <span>{{item.Value}}</span> {# 字段的值 #}
    </p>
    {% endfor %}
</div>

结合具体业务场景，例如，某个产品模型定义了一个名为specifications的自定义字段，其值为一段HTML代码或一个JSON字符串，您可以在模板中这样处理：

{% archiveDetail productSpecs with name="specifications" %}<div class="product-specs">{{productSpecs|safe}}</div>

或者，如果arcimages是一个自定义的组图字段，您可以这样展示：

{% archiveDetail customImages with name="arcimages" %}
<div class="custom-gallery">
{% for imgUrl in customImages %}
    <img src="{{imgUrl}}" alt="产品图">
{% endfor %}
</div>

实际应用中的文档详情展示

通过archiveDetail及相关标签的组合使用，我们可以轻松构建出功能丰富、信息详尽的文档详情页。

考虑一个典型的文章详情页面，它需要显示文章标题、所属分类、发布时间、关联标签、阅读量以及文章内容。模板代码可能类似这样：

<article>
    <h1>{% archiveDetail with name="Title" %}</h1>
    <div class="meta-info">
        {% archiveDetail currentCategory with name="Category" %}
        <span class="category-link"><a href="{{currentCategory.Link}}">{{currentCategory.Title}}</a></span>
        <span>发布于：{% archiveDetail with name="CreatedTime" format="2006-01-02" %}</span>
        {% archiveDetail currentDocId with name="Id" %}
        {% tagList tags with itemId=currentDocId %}
        <span class="tags">标签：
            {% for tag in tags %}<a href="{{tag.Link}}">{{tag.Title}}</a> {% endfor %}
        </span>
        {% endtagList %}
        <span>阅读：{% archiveDetail with name="Views" %}次</span>
    </div>
    <div class="article-content">
        {% archiveDetail articleBody with name="Content" render=true lazy="data-src" %}{{articleBody|safe}}
    </div>
</article>

而对于一个产品详情页，除了产品名称和图片，通常还需要展示其特有的参数、简介和详细描述。如果我们在产品模型中定义了brand（品牌）、model（型号）等自定义字段，模板可以这样实现：

<div class="product-detail-container">
    <div class="product-media">
        <img src="{% archiveDetail with name="Logo" %}" alt="{% archiveDetail with name="Title" %}" class="main-product-image">
        {% archiveDetail galleryImages with name="Images" %}
        <div class="product-gallery">
            {% for img in galleryImages %}<img src="{{img}}">{% endfor %}
        </div>
    </div>
    <div class="product-info">
        <h1>{% archiveDetail with name="Title" %}</h1>
        <p class="product-description">{% archiveDetail with name="Description" %}</p>
        <div class="product-specs">
            <h3>产品参数</h3>
            {% archiveParams productParams %}
            <ul>
                {% for item in productParams %}
                <li><strong>{{item.Name}}：</strong>{{item.Value}}</li>
                {% endfor %}
            </ul>
            {% endarchiveParams %}
        </div>
        <div class="full-description">
            <h3>详细介绍</h3>
            {% archiveDetail productContent with name="Content" render=true %}{{productContent|safe}}
        </div>
    </div>
</div>

总结

archiveDetail标签是AnQiCMS模板开发中不可或缺的利器。它提供了直观且强大的方式来访问和展示文档的各种信息，无论是内置的标准字段还是根据业务需求定制的自定义字段。熟练掌握其用法和参数，将使您在网站内容呈现上拥有极高的自由度和效率，确保每一篇内容都能以最完美的状态呈现在您的用户面前。

常见问题解答

我的自定义字段在模板中不显示，是哪里出了问题？ 首先，请确保您在AnQiCMS后台的内容模型中正确定义了这些自定义字段，并且在发布文档时为它们填写了内容。其次，检查模板中自定义字段的name参数是否与后台定义的“调用字段”名称完全一致，并且注意大小写。AnQiCMS的模板标签对大小写是敏感的。如果自定义字段的值是空字符串或nil，它可能不会输出任何内容，您可以使用过滤器如default来设置默认值进行排查。

我如何获取当前文档所属分类的更多信息，例如分类的Logo或Banner图？ 当您通过{% archiveDetail docCategory with name="Category" %}获取到文档的分类对象后，docCategory变量就包含了分类的所有属性，例如docCategory.Link、docCategory.Title。如果需要获取分类的Logo或Banner图等，可以直接使用docCategory.Logo或docCategory.Images。若需要获取更复杂的分类自定义字段或不想依赖archiveDetail获取的分类对象，您也可以使用categoryDetail标签，通过{% categoryDetail with name="Logo" id=docCategory.Id %}来获取指定ID分类的更多详情。

为什么我的Content字段显示的是HTML代码或者Markdown语法，而不是渲染后的内容？ 如果Content字段显示的是原始HTML代码，可能是因为您没有使用|safe过滤器。AnQiCMS为了安全，会对HTML标签进行自动转义，|safe过滤器会告诉模板引擎这是一个安全的内容，无需转义。如果显示的是Markdown语法，那可能是后台未开启Markdown编辑器，或者在archiveDetail标签中没有设置render=true参数来强制进行Markdown到HTML的转换。请根据您的需求添加|safe过滤器和render参数。