在网站内容管理中，高效地组织和呈现信息至关重要。AnqiCMS 提供了强大的模板标签系统，其中 categoryList 标签便是用于灵活显示文章或产品分类的核心工具。通过掌握这一标签的使用，用户可以轻松地在前台构建出层次分明、功能完善的分类导航，无论是按层级展示还是根据内容模型（如文章、产品）进行筛选，都能游刃有余。

认识 categoryList 标签

categoryList 标签的主要作用是从 AnqiCMS 后台获取预设的分类数据，并以列表形式在前台页面展现。它的基本结构如下：

{% categoryList categories with ... %}
    {# 在这里循环输出分类信息 #}
{% endcategoryList %}

在这里，categories 是一个自定义的变量名，用于在标签内部循环时存储每个分类的数据。with 关键字后面则跟着一系列参数，用于控制要获取哪些分类以及如何进行筛选和排序。

核心参数解析：精细化控制分类展示

categoryList 标签的强大之处在于其丰富的参数选项，这些参数让您可以根据实际需求灵活地筛选和组织分类信息。

  1. 按内容模型筛选 (moduleId) AnqiCMS 的一大特色是其灵活的内容模型。每个分类都必须归属于一个特定的内容模型，例如“文章模型”或“产品模型”。当您希望显示特定类型的内容分类时，moduleId 参数就派上用场了。

    • 要显示“文章模型”下的所有分类，通常设置为 moduleId="1"。
    • 要显示“产品模型”下的所有分类，通常设置为 moduleId="2"。 （具体的模型ID可以在AnqiCMS后台“内容管理”->“内容模型”中查看）

    例如，如果您只想列出所有产品分类：

    {% categoryList productCategories with moduleId="2" %}
    {# 循环输出产品分类 #}
{% endcategoryList %}

  2. 构建层级结构 (parentId) 网站导航往往是多层级的，parentId 参数正是为了应对这种需求而生。

    • 显示顶级分类： 设置 parentId="0" 将只获取指定内容模型下的所有顶级分类。
    • 显示当前分类的子分类： 在分类列表页或详情页中，如果您想显示当前分类的所有直接子分类，可以省略 parentId 参数，系统会自动识别当前分类ID并获取其子分类。
    • 显示当前分类的兄弟分类： 如果您希望在某个分类页面展示其同级的所有分类（即兄弟分类），可以将 parentId 设置为 parentId="parent"。这通常在内容列表页中结合当前分类使用。

    例如，要显示所有文章顶级分类：

    {% categoryList topArticleCategories with moduleId="1" parentId="0" %}
    {# 循环输出文章顶级分类 #}
{% endcategoryList %}

  3. 获取所有分类 (all) 在某些特定场景下，您可能需要列出某个模型下的所有分类，而不考虑其层级关系，例如在后台管理界面或者构建一个完整的网站地图时。此时，可以将 all 参数设置为 true。

    {% categoryList allCategories with moduleId="1" all=true %}
    {# 循环输出所有文章分类，不分层级 #}
{% endcategoryList %}

  4. 控制显示数量 (limit) 如果您只想显示固定数量的分类，可以使用 limit 参数来限制返回的条目数量。例如 limit="10" 将只显示前10个分类。您还可以使用 offset 模式，如 limit="2,10" 表示从第2个分类开始，获取10个分类。

  5. 多站点兼容 (siteId) AnqiCMS 支持多站点管理。如果您部署了多个站点并希望调用特定站点的数据，可以通过 siteId 参数来指定站点ID。一般情况下，如果只管理一个站点，则无需设置此参数。

获取与展示分类信息：item 变量详解

在 categoryList 标签内部的循环中，每个 item 变量都包含了当前分类的详细信息，您可以根据需要进行调用和展示：

  • {{ item.Id }}：分类的唯一ID。
  • {{ item.Title }}：分类的显示名称。
  • {{ item.Link }}：分类页面的访问链接，AnqiCMS 会根据伪静态规则自动生成。
  • {{ item.Description }}：分类的简介或描述。
  • {{ item.ParentId }}：当前分类的上级分类ID。
  • {{ item.HasChildren }}：一个布尔值，指示当前分类是否包含子分类。这对于构建动态嵌套导航非常有用。
  • {{ item.Spacer|safe }}：一个非常有用的字段，它会根据分类的层级自动生成缩进或前缀，方便在列表中直观地显示层级关系（例如：├─、└─）。记得使用 |safe 过滤器以确保HTML字符正确渲染。
  • {{ item.Logo }} 和 {{ item.Thumb }}：分类的大图和缩略图地址。
  • {{ item.ArchiveCount }}：该分类下（包含子分类）的文档总数。

实战演练：灵活构建分类导航

现在，让我们通过几个实际场景来展示 categoryList 标签的灵活运用。

场景一：显示特定内容模型下的顶级分类

假设我们需要在首页显示所有“文章模型”下的顶级分类，作为主要导航的一部分。

<nav class="main-nav">
    <ul class="category-list-top">
        {% categoryList articleCategories with moduleId="1" parentId="0" %}
            {% for category in articleCategories %}
                <li><a href="{{ category.Link }}">{{ category.Title }}</a></li>
            {% endfor %}
        {% else %}
            <li>暂无文章分类</li>
        {% endcategoryList %}
    </ul>
</nav>

这段代码会筛选出 moduleId 为 1（文章模型）且 parentId 为 0（顶级分类）的所有分类，并以无序列表的形式展示它们的名称和链接。

场景二：构建多层级嵌套分类导航

更常见的需求是构建一个具有多层级结构的导航菜单，例如“产品中心”下有多个产品系列，每个系列下又有具体的产品类型。这时，可以使用嵌套的 categoryList 标签并结合 HasChildren 属性。

”`twig 

<h3>产品分类</h3>
{% categoryList productCategories with moduleId="2" parentId="0" %}
    <ul class="level-1-categories">
        {% for category in productCategories %}
            <li {% if category.HasChildren %}class="has-submenu"{% endif %}>
                <a href="{{ category.Link }}">{{ category.Title }}</a>
                {% if category.HasChildren %}
                    {# 递归调用子分类，AnqiCMS模板引擎可以很好地