`categoryDetail`标签如何获取并显示特定分类的描述、Logo等详细信息？

在 AnQiCMS 的模板开发中，获取并展示分类的详细信息是构建丰富且用户友好页面的关键一环。categoryDetail 标签正是为此而生，它能帮助你轻松地在页面的任何位置调取特定分类的描述、Logo、自定义字段等详细内容。

categoryDetail 标签的核心功能

categoryDetail 标签的主要作用是获取单个分类的详细数据。无论你是在分类列表页希望显示当前分类的额外信息，还是在文章详情页需要展示所属分类的Logo和简介，甚至是想在网站的任何一个角落引用某个特定分类的详细数据，这个标签都能派上用场。

它的基本使用形式通常是：{% categoryDetail 变量名称 with name="字段名称" %}。其中，变量名称是一个可选参数，如果你想将获取到的数据赋值给一个变量以便后续多次使用或进行更复杂的逻辑处理，就可以指定它。如果只是想直接输出某个字段的值，则可以省略 变量名称。而 name 参数则是核心，它告诉标签你希望获取分类的哪一个具体字段的信息。

如何获取特定分类的详细信息

在使用 categoryDetail 标签时，首先需要明确你想获取哪个分类的信息。AnQiCMS 提供了几种灵活的方式来指定目标分类：

1. 自动识别当前分类： 如果你在分类详情页（例如 article/list-{分类ID}.html 或 product/list-{分类ID}.html），categoryDetail 标签会智能地识别当前页面所对应的分类，并自动获取其信息。此时，你通常无需额外指定分类 ID。

2. 通过分类 ID 指定： 你可以通过 id 参数来精确指定要获取的分类。例如，{% categoryDetail with name="Title" id="10" %} 将会获取 ID 为 10 的分类的标题。

3. 通过分类 URL 别名（token）指定： 如果你更喜欢使用分类的 URL 别名来标识，可以使用 token 参数。例如，{% categoryDetail with name="Description" token="about-us" %} 会获取别名为 “about-us” 的分类的描述。

4. 多站点场景下的指定： 对于部署了多个站点的 AnQiCMS，如果你需要获取非当前站点的分类信息，可以使用 siteId 参数来指定站点 ID。例如，{% categoryDetail with name="Title" id="10" siteId="2" %}。

name 参数可用的字段详解

name 参数允许你选择分类的各种详细信息。以下是常用的字段及其使用示例：

• 分类 ID (Id)、分类标题 (Title)、分类链接 (Link)、分类描述 (Description)： 这些是最基础的分类信息，常用于构建导航、面包屑或简单的分类介绍。

  <div>当前分类ID：{% categoryDetail with name="Id" %}</div>
  <h2><a href="{% categoryDetail with name="Link" %}">{% categoryDetail with name="Title" %}</a></h2>
  <p>{% categoryDetail with name="Description" %}</p>
  

• 分类内容 (Content)： 如果你的分类包含了富文本编辑器编辑的详细内容，可以使用 Content 字段获取。需要注意的是，如果内容中包含 HTML 标签，为了在页面上正确渲染而不是显示原始代码，通常需要配合 |safe 过滤器。如果后台开启了 Markdown 编辑器，内容是 Markdown 格式，你可以通过 render=true 参数让标签自动将其转换为 HTML。

  <div>
      {% categoryDetail categoryContent with name="Content" render=true %}
      {{ categoryContent|safe }}
  </div>
  

• 分类缩略图大图 (Logo)、分类缩略图 (Thumb)： 这些字段用于获取分类的代表性图片。Logo 通常是较大的主图，Thumb 则是自动生成的缩略图。

  <img src="{% categoryDetail with name="Logo" %}" alt="{% categoryDetail with name="Title" %}" />
  

  在实际使用中，为了避免图片路径为空导致页面错误，建议进行判断：

  {% set categoryLogo = categoryDetail with name="Logo" %}
  {% if categoryLogo %}
      <img src="{{ categoryLogo }}" alt="{% categoryDetail with name="Title" %}" />
  {% endif %}
  

• 分类 Banner 组图 (Images)： 如果分类支持上传多张图片作为 Banner 或轮播图，Images 字段会返回一个图片 URL 数组。你需要使用 for 循环来遍历并显示这些图片。

  {% categoryDetail categoryBanners with name="Images" %}
  <div class="category-banner-slider">
      {% for imgUrl in categoryBanners %}
          <img src="{{ imgUrl }}" alt="{% categoryDetail with name="Title" %}" />
      {% endfor %}
  </div>
  

• 上级分类 ID (ParentId)： 这个字段对于构建多级分类导航或判断分类层级关系非常有用。

  <span>上级分类ID：{% categoryDetail with name="ParentId" %}</span>
  

• 分类的文档数量 (ArchiveCount)： 显示当前分类下包含多少篇文章或产品。

  <span>该分类下共有文档：{% categoryDetail with name="ArchiveCount" %} 篇</span>
  

• 文档模型设置的分类其他字段参数（自定义字段）： AnQiCMS 强大的内容模型功能允许你为分类添加各种自定义字段。这些自定义字段也可以通过 categoryDetail 标签获取。你可以直接通过自定义字段的 调用字段 名称来获取其值，或者获取一个包含所有自定义字段的 Extra 对象，然后通过循环遍历它们。

  {# 获取名为 "custom_field_name" 的自定义字段值 #}
  <span>自定义字段值：{% categoryDetail with name="custom_field_name" %}</span>
  
  {# 遍历所有自定义字段 #}
  {% categoryDetail categoryExtraFields with name="Extra" %}
  {% for field in categoryExtraFields %}
      <div>{{ field.Name }}：{{ field.Value }}</div>
  {% endfor %}
  

实用示例：构建分类页面的 Banner 和简介

假设我们正在构建一个产品分类页面，希望在页面顶部显示该分类的 Banner 图、标题和详细描述，并列出该分类下的自定义属性。

<div class="category-header">
    {# 获取并显示分类的 Banner 图，并判断是否存在 #}
    {% categoryDetail bannerImages with name="Images" %}
    {% if bannerImages %}
        {# 假设我们只取第一张图作为 Banner #}
        {% set categoryBanner = bannerImages[0] %}
        <div class="category-banner" style="background-image: url('{{ categoryBanner }}');">
            <h1>{% categoryDetail with name="Title" %}</h1>
        </div>
    {% else %}
        {# 如果没有 Banner 图，只显示标题 #}
        <h1>{% categoryDetail with name="Title" %}</h1>
    {% endif %}

    <div class="category-description">
        <p>{% categoryDetail with name="Description" %}</p>
        {# 显示分类的详细内容，包含HTML #}
        {% categoryDetail categoryRichContent with name="Content" render=true %}
        {{ categoryRichContent|safe }}
    </div>

    {# 显示自定义属性，例如“适用人群”、“特点”等 #}
    <div class="category-attributes">
        <h3>分类特色</h3>
        <ul>
        {% categoryDetail categoryCustomFields with name="Extra" %}
        {% for field in categoryCustomFields %}
            {# 排除不想显示的字段，例如“内部备注” #}
            {% if field.Name != '内部备注' %}
                <li><strong>{{ field.Name }}：</strong>{{ field.Value }}</li>
            {% endif %}
        {% endfor %}
        </ul>
    </div>
</div>

通过这些方法，你可以充分利用 categoryDetail 标签，将分类数据以丰富的形式呈现在你的 AnQiCMS 网站上，从而提升用户体验和内容表现力。

常见问题 (FAQ)

1. 为什么我使用 {% categoryDetail with name="Content" %} 获取到的内容是原始 HTML 或 Markdown 代码，而不是渲染后的样式？

这是因为 AnQiCMS 默认会对输出进行安全转义，以防止 XSS 攻击。如果你的分类内容包含 HTML 标签或 Markdown 格式，需要使用 |safe 过滤器来告诉模板这部分内容是安全的，应该直接作为 HTML 渲染。如果内容是 Markdown 格式，你还需要加上 render=true 参数，例如：{% categoryDetail categoryContent with name="Content" render=true %}{{ categoryContent|safe }}。

2. 如何获取一个分类的 Logo 或 Banner，并且在没有图片时不会显示一个 broken image 图标？

你可以先将图片路径赋值给一个变量，然后使用 if 语句判断这个变量是否存在图片路径。如果存在，则渲染 <img> 标签，否则