分类详情标签`categoryDetail`如何获取并显示特定分类的详细信息？

在安企CMS的网站内容运营中，我们经常需要精确地获取并展示特定分类的详细信息。无论是展示分类的名称、描述，还是其关联的图片、内容，categoryDetail标签都能提供灵活且强大的支持，帮助我们构建动态丰富的分类页面。

categoryDetail标签的核心功能与基本用法

categoryDetail标签旨在获取单个分类的详尽数据。它的基本结构简洁明了，通常包含以下几个部分：

{% categoryDetail 变量名称 with name="字段名称" id="分类ID" %}

  • 变量名称（可选）：你可以为获取到的分类详情数据指定一个变量名（例如 myCategory），这样在后续的模板代码中就可以通过这个变量名来引用数据。如果你不指定变量名，标签会直接输出指定字段的值。
  • name="字段名称"：这是最核心的参数，用于指定你想要获取的分类数据的具体字段，比如分类的标题Title、描述Description等。
  • id="分类ID"（可选）：如果你想获取网站中某个特定ID的分类信息，可以在这里指定其ID。如果当前页面本身就是一个分类页面（例如分类列表页），并且你希望获取当前分类的详情，那么你可以省略id参数，categoryDetail标签会智能地获取当前页面的分类信息。
  • token="分类URL别名"（可选）：与id类似，token参数允许你通过分类的URL别名来指定要获取的分类。这在某些场景下比使用数字ID更直观。
  • siteId="站点ID"（可选）：对于启用了多站点功能的安企CMS，如果你需要获取非当前站点的分类数据，可以通过siteId来指定目标站点。

常用字段及其应用

categoryDetail标签通过name参数可以获取到分类的众多属性，这里我们列举一些常用的字段及其在模板中的应用。

1. 分类基础信息：Id, Title, Link, Description

这些是分类最基本且常用的信息，获取方式非常直接。

  • 分类ID (Id)：{% categoryDetail with name="Id" %} 或者 {{ category.Id }} (在分类页可以直接通过category对象访问)。
  • 分类标题 (Title)：{% categoryDetail with name="Title" %}，通常用于显示分类名称。
  • 分类链接 (Link)：{% categoryDetail with name="Link" %}，用于构建分类的跳转链接。
  • 分类描述 (Description)：{% categoryDetail with name="Description" %}，通常用于分类页面的SEO描述或简介。

示例：在分类页面头部显示分类信息

<div class="category-header">
    <h1>{% categoryDetail with name="Title" %}</h1>
    <p>{% categoryDetail with name="Description" %}</p>
    <a href="{% categoryDetail with name="Link" %}" class="more-link">查看更多</a>
</div>

2. 分类内容 (Content)

如果你的分类有专门的介绍内容（例如“关于我们”分类的详细介绍），可以通过Content字段获取。这个字段尤其要注意其渲染方式。

示例：显示分类的详细内容

<div class="category-content">
    {% categoryDetail categoryMainContent with name="Content" %}
    {{ categoryMainContent|safe }}
</div>

这里|safe过滤器至关重要。安企CMS的模板引擎默认会对HTML内容进行转义以防止XSS攻击。如果分类内容包含HTML标签，为了让它们正常渲染，你需要使用|safe过滤器。如果分类内容是用Markdown编写的，你可以通过添加render=true参数，让系统自动将其转换为HTML：

<div class="category-content">
    {% categoryDetail categoryMainContent with name="Content" render=true %}
    {{ categoryMainContent|safe }}
</div>

3. 分类图片：Logo, Thumb, Images

分类页面经常需要展示图片，安企CMS提供了多种图片字段。

  • 分类缩略图大图 (Logo)：通常是分类的主要展示图。
  • 分类缩略图 (Thumb)：经过系统压缩或裁剪后的缩略图，适合在列表页等地方使用以提升加载速度。
  • 分类Banner组图 (Images)：如果后台为分类设置了多张Banner图，这个字段会返回一个图片URL的数组。

示例：显示分类Logo和Banner组图

<div class="category-banner">
    <img src="{% categoryDetail with name="Logo" %}" alt="{% categoryDetail with name="Title" %}">

    <h3>分类相册</h3>
    {% categoryDetail categoryBanners with name="Images" %}
    {% if categoryBanners %}
        <div class="image-gallery">
            {% for imgUrl in categoryBanners %}
                <img src="{{ imgUrl }}" alt="分类图片 - {% categoryDetail with name="Title" %}">
            {% endfor %}
        </div>
    {% endif %}
</div>

如果Images是一个组图，但你只需要显示第一张图片作为封面，可以这样操作：

{% categoryDetail bannerImages with name="Images" %}
{% if bannerImages %}
    {% set firstBanner = bannerImages[0] %} {# 获取数组的第一个元素 #}
    <div class="page-banner" style="background-image: url({{ firstBanner }});">
        {# 其他内容 #}
    </div>
{% endif %}

4. 分类的文档数量 (ArchiveCount)

这个字段非常实用，可以显示当前分类下包含多少篇文章或产品。

示例：显示分类下的文章数量

<p>本分类共有 {% categoryDetail with name="ArchiveCount" %} 篇文章。</p>

5. 上级分类ID (ParentId)

在多级分类结构中，获取当前分类的父级ID有时会很有用，例如用于构建面包屑导航或上级分类链接。

示例：获取并显示上级分类ID

<p>当前分类的上级分类ID是：{% categoryDetail with name="ParentId" %}</p>

6. 自定义字段

安企CMS的强大之处在于其灵活的内容模型。如果你在后台为分类模型添加了自定义字段，categoryDetail标签同样可以获取它们。

示例：获取并显示所有自定义字段

<div class="category-custom-fields">
    {% categoryDetail extras with name="Extra" %}
    {% for field in extras %}
        <div>{{ field.Name }}：{{ field.Value }}</div>
    {% endfor %}
</div>

如果你知道自定义字段的具体名称（例如 author、price），也可以直接通过name参数获取：

<p>分类作者：{% categoryDetail with name="author" %}</p>
<p>分类价格区间：{% categoryDetail with name="price" %}</p>

实际应用场景示例

假设我们有一个“新闻动态”的分类列表页，我们希望在每个新闻分类的卡片上显示其名称、描述、缩略图，并知道它有多少篇文章。

{# 假设我们正在循环显示顶级新闻分类 #}
{% categoryList newsCategories with moduleId="1" parentId="0" %}
    {% for categoryItem in newsCategories %}
    <div class="news-category-card">
        <a href="{{ categoryItem.Link }}">
            <img src="{% categoryDetail with name="Thumb" id=categoryItem.Id %}" alt="{{ categoryItem.Title }}">
            <h2>{{ categoryItem.Title }}</h2>
            <p>{{ categoryItem.Description|truncatechars:100 }}</p>
            <span>（共 {% categoryDetail with name="ArchiveCount" id=categoryItem.Id %} 篇文章）</span>
        </a>
    </div>
    {% endfor %}
{% endcategoryList %}

在这个例子中，我们在categoryList的循环内部，通过categoryDetail标签并传入当前循环项的id（即categoryItem.Id），来获取每个分类更详细的缩略图和文章数量。

总结

categoryDetail标签是安企CMS模板开发中获取和展示分类信息不可或缺的工具。它提供了从基本标题、描述到复杂内容、图片组、自定义字段等一系列数据接口。通过灵活运用name、id、token等参数，以及对Content字段的render处理和Images数组的遍历，我们可以轻松构建出高度定制化、信息丰富的分类页面，大大提升网站内容的呈现效果和用户体验。

常见问题 (FAQ)

1. 如果我想在非分类页面获取某个分类的详情信息，应该怎么做？

答：在非分类页面（例如首页、文章详情页或自定义页面），你可以通过id或token参数来明确指定要获取哪个分类的详情。比如，如果你想在首页显示ID为5的“关于我们”分类的描述，可以这样写：{% categoryDetail with name="Description" id="5" %}。

**2. `categoryDetail