如何使用`categoryList`和`categoryDetail`标签来构建和显示分类导航及详情？
在网站内容管理中，分类导航和详情页是用户浏览网站、获取信息的核心路径，也是搜索引擎理解网站结构的重要依据。一个清晰、直观的分类体系不仅能大幅提升用户体验，更能有效助力网站的SEO表现。对于安企CMS的用户而言，灵活运用系统提供的categoryList和categoryDetail这两个模板标签，可以轻松构建出功能强大、美观实用的分类导航和详情展示。
一、构建灵活的分类导航：深入了解 categoryList 标签
categoryList 标签主要用于获取网站的分类列表。无论您是想在顶部展示主分类、在侧边栏构建多级分类树，还是在首页展示特定分类下的子分类，这个标签都能提供强大的支持。
1. 标签的基本用法和核心参数
在使用 categoryList 标签时，我们通常会定义一个变量来接收获取到的分类数据，例如 {% categoryList categories with ... %}...{% endcategoryList %}。其中，categories 就是一个包含多个分类信息的数组对象，我们可以通过循环遍历它来展示每一个分类。
以下是几个常用且关键的参数，它们决定了您能获取到哪些分类以及如何组织它们：
moduleId：指定内容模型 您的网站可能有多种内容类型，如文章、产品等，它们在安企CMS中被称为“内容模型”。通过moduleId="1"（文章模型为例）或moduleId="2"（产品模型为例）来指定您希望获取哪个内容模型下的分类。parentId：控制层级关系 这是构建层级导航的关键参数。- 当
parentId="0"时，您将获取到指定模型下的所有顶级分类。这是构建主导航或一级分类列表的常用方式。 - 若想获取某个特定分类下的所有子分类，只需将
parentId设置为该父分类的ID即可。 - 一个非常实用的技巧是，当您处于某个分类页面（例如文章列表页）时，如果想获取当前分类的兄弟分类（即同级别的其他分类），可以将
parentId设置为"parent"。系统会自动识别当前分类的父级，并返回其所有子分类（包括当前分类本身）。
- 当
limit：限制显示数量 如果您只想显示固定数量的分类，比如首页只展示5个热门分类，可以使用limit="5"。更高级的用法是limit="2,10"，这意味着从第2个分类开始，获取10个分类。all：获取所有分类 如果您需要获取指定模型下的所有分类，无论层级如何，都可以使用all=true。这在构建全站分类地图或进行一些特殊展示时非常有用。
2. categoryList 的实际应用场景
构建主导航
{% categoryList categories with moduleId="1" parentId="0" %} <ul class="main-nav"> {% for item in categories %} <li {% if item.IsCurrent %}class="active"{% endif %}> <a href="{{ item.Link }}">{{ item.Title }}</a> </li> {% endfor %} </ul> {% endcategoryList %}这段代码会获取文章模型下的所有顶级分类，并生成一个简单的导航列表。
item.IsCurrent可以帮助您判断当前分类是否为用户正在访问的页面所属分类，从而添加高亮样式。创建多级嵌套侧边栏 当您需要展示复杂的分类结构时，可以利用
categoryList的嵌套调用：{% categoryList topCategories with moduleId="1" parentId="0" %} <ul class="sidebar-menu"> {% for topCategory in topCategories %} <li> <a href="{{ topCategory.Link }}">{{ topCategory.Title }}</a> {% if topCategory.HasChildren %} {# 判断是否有子分类 #} {% categoryList subCategories with parentId=topCategory.Id %} <ul class="sub-menu"> {% for subCategory in subCategories %} <li><a href="{{ subCategory.Link }}">{{ subCategory.Title }}</a></li> {% endfor %} </ul> {% endcategoryList %} {% endif %} </li> {% endfor %} </ul> {% endcategoryList %}这里的
topCategory.HasChildren是一个非常有用的字段，它可以帮助我们判断当前分类是否有子分类，从而决定是否需要继续嵌套调用categoryList。结合文档列表展示 在首页或内容聚合页，我们经常需要显示不同分类下的文章列表，
categoryList也能很好地与archiveList（文档列表标签）配合：{% categoryList featureCategories with moduleId="1" parentId="0" limit="3" %} <div class="category-section"> {% for category in featureCategories %} <h3><a href="{{ category.Link }}">{{ category.Title }}</a></h3> <ul class="article-list"> {% archiveList articles with categoryId=category.Id limit="5" %} {# 获取当前分类下的5篇文章 #} {% for article in articles %} <li><a href="{{ article.Link }}">{{ article.Title }}</a></li> {% endfor %} {% endarchiveList %} </ul> {% endfor %} </div> {% endcategoryList %}
在 categoryList 循环中，item（分类对象）提供了丰富的字段信息，如 Id (分类ID)、Title (分类名称)、Link (分类链接)、Description (分类描述)、Logo (缩略图大图)、Thumb (缩略图)、HasChildren (是否有子分类)、IsCurrent (是否当前链接) 等，这些都为模板开发带来了极大的灵活性。
二、展示分类的详细信息：掌握 categoryDetail 标签
当用户点击分类导航，进入到具体的分类页面时，我们往往需要展示该分类的详细信息，例如分类的介绍、Banner图等。此时，categoryDetail 标签便派上了用场。它用于获取单个分类的详细数据。
1. 标签的基本用法和核心参数
categoryDetail 标签通常用于直接输出特定分类的某个字段值，例如 {% categoryDetail with name="Title" %}。
id或token：指定分类 通常情况下，当您在分类详情页使用categoryDetail时，无需指定id或token，系统会智能地识别当前页面的分类ID并自动获取其详情。但如果您需要在其他页面（例如文章详情页）获取某个特定分类的信息，可以通过id="10"（指定分类ID为10）或token="web-design"（指定分类URL别名为web-design）来明确指定目标分类。name：获取指定字段 这是categoryDetail最重要的参数，它决定了您要获取分类的哪一项信息。常用的name值包括：Id：分类ID。Title：分类标题。Link：分类链接。Description：分类描述，通常用于页面TDK或分类简介。Content：分类详情内容，后台可以在“文档分类”中编辑。Logo：分类的Banner图或大尺寸缩略图。Thumb：分类的小尺寸缩略图。Images：分类 Banner 组图，这是一个数组，通常需要循环输出。ArchiveCount：该分类下的文档数量。- 以及您在后台“内容模型”中为分类自定义的任何字段。
2. categoryDetail 的实际应用场景
在分类页显示分类名称和描述
<div class="category-header"> <h1>{% categoryDetail with name="Title" %}</h1> <p>{% categoryDetail with name="Description" %}</p> </div>这段代码会在分类列表页的顶部，显示当前分类的名称和描述，方便用户了解当前分类的主题。
展示分类 Banner 图 如果您的分类在后台上传了 Banner 图，可以在分类页面顶部展示：
{% categoryDetail categoryBanner with name="Logo" %} {% if categoryBanner %} <div class="category-banner" style="background-image: url('{{ categoryBanner }}');"> {# 可以叠加其他内容 #} </div> {% endif %}这里我们先将
Logo字段的值赋给categoryBanner变量，然后判断变量是否存在以避免图片路径为空的情况。在面包屑导航中使用 在文章详情页，面包屑导航通常需要显示文章所属分类的名称和链接。这时，即使我们不在分类页，也可以通过文章的
CategoryId来获取分类详情：{# 假设这里是文章详情页，并且文章对象名为 archive #} {% breadcrumb crumbs %} <ul> {% for item in crumbs %} <li><a href="{{item.Link}}">{{item.Name}}</a></li> {% endfor %} </ul> {% endbreadcrumb %} {# 也可以直接获取文章所属分类的名称和链接 #} <p>所属分类：<a href="{% categoryDetail with name='Link' id=archive.CategoryId %}">{% categoryDetail with name='Title' id=archive.CategoryId %}</a></p>调用分类自定义字段 如果您在后台为分类模型添加了自定义字段，例如“分类负责人” (
manager)，您可以通过{% categoryDetail with name="manager" %}来直接调用并显示其值。如果需要循环显示所有自定义字段，可以这样处理：{% categoryDetail extras with name="Extra" %} {% for field in extras %} <div>{{ field.Name }}：{{ field.Value }}</div> {% endfor %}
三、categoryList 与 categoryDetail 的协同与进阶
这两个标签并非孤立存在，它们在实际模板开发中往往协同工作，发挥更大的作用。
一个常见的场景是在使用 categoryList 循环输出分类时，每个 item 已经包含了分类的基本信息（如 Id、Title、Link）。如果需要获取更复杂的、不在 item 直接提供的分类信息（例如分类的 Content 或某个自定义字段），可以在 categoryList 的循环内部，通过 categoryDetail 标签，并传入 item.Id 来获取更完整的分类详情。
例如，在一个分类列表中，除了显示分类名称，还想显示每个分类的缩略图：
{% categoryList categories with moduleId="1" parentId="0" %}
<ul class="category-grid">
{% for category in categories %}
<li>
<a href="{{ category.Link }}">
<img src="{% categoryDetail with name='Thumb' id=category.Id %}" alt="{{ category.Title }}">
<h4>{{ category.Title }}</h4>
<p>{{ category.Description | truncatechars:50 }}</p>
</a>
</li>
{% endfor %}
</ul>
{% endcategoryList %}
这里，{% categoryDetail with name='Thumb' id=category.Id %} 巧妙地在循环中，针对每一个分类 category，获取了其对应的缩略图。
四、实践建议与总结
- 规划分类结构：在动手开发模板之前，务必在安企CMS后台规划好清晰的分类层级和内容模型，这将直接影响您标签调用的方式。
- 优化SEO：合理利用
Title、Description和自定义URL别名 (token)，为每个分类设置有吸引力且包含关键词的TDK信息，有助于搜索引擎更好地索引您的分类页面。 - 保持模板简洁：善用模板的继承 (
extends) 和包含 (include) 功能，将重复的代码片段（如导航菜单的子菜单结构）模块化，使得模板结构清晰、易于维护。例如，多级嵌套的分类导航可以封装成一个宏 (macro) 来调用，避免代码冗余。 - 灵活运用字段：除了默认