如何使用`categoryList`标签获取并循环展示指定内容模型下的分类列表？

作为一名长期深耕AnQiCMS内容运营的专家，我深知分类列表在网站结构和用户体验中的重要性。灵活运用categoryList标签，能够帮助我们高效地组织内容，构建清晰的导航体系，并为读者提供更精准的内容发现路径。下面，我将详细阐述如何使用categoryList标签来获取并循环展示指定内容模型下的分类列表。

使用 AnQiCMS 的 categoryList 标签获取并循环展示指定内容模型下的分类列表

在AnQiCMS的模板开发中，categoryList标签是用于获取网站分类数据核心工具。它允许我们根据不同的需求，如内容模型、层级关系等，精确地提取和展示分类信息。这对于构建动态导航、分类列表页侧边栏、内容筛选器等功能至关重要。

理解 categoryList 标签的核心功能

categoryList标签的主要作用是从数据库中检索出符合特定条件的分类数据。它支持多种参数来精细控制数据的获取范围和方式，并以可循环遍历的对象形式返回结果，方便我们在模板中进行渲染。AnQiCMS的模板引擎语法类似Django，因此在使用categoryList时，我们通常会结合{% for ... in ... %}循环标签来遍历获取到的分类数据。

关键参数解析：指定内容模型与层级控制

要实现获取指定内容模型下的分类列表，moduleId参数是核心。同时，parentId参数则用于控制分类的层级关系，帮助我们构建多级分类导航。

moduleId：指定内容模型的唯一标识

moduleId参数用于筛选出属于特定内容模型的分类。在AnQiCMS中，内容模型是我们自定义内容结构的基础，例如“文章”模型、“产品”模型等。每个内容模型都有一个唯一的ID。

• 使用方法示例： moduleId="1" 或 moduleId="2"。如果“文章”模型的ID是1，“产品”模型的ID是2，那么moduleId="1"将只获取文章分类，而moduleId="2"则只获取产品分类。
• 应用场景： 当我们需要在网站的不同区域（例如文章列表页的侧边栏显示文章分类，产品列表页的侧边栏显示产品分类）展示不同内容模型的分类时，此参数必不可少。

parentId：控制分类的层级关系

parentId参数用于控制我们想要获取的分类所属的层级。

• 获取顶级分类： 设置parentId="0"将获取所有内容模型下的顶级分类。当我们想构建主导航菜单时，这非常有用。
• 获取子分类： 在循环遍历父级分类时，我们可以使用当前父级分类的Id作为子级分类的parentId，从而实现多级分类的嵌套显示。
• 获取兄弟分类： 将parentId设置为"parent"（仅在当前页面是分类列表页时有效），可以获取当前分类的兄弟分类。

limit：控制显示数量与偏移

limit参数用于限制返回的分类数量。它支持两种模式：

• 固定数量： limit="10"表示最多显示10条分类。
• 偏移模式： limit="2,10"表示从第2条记录开始，获取10条分类数据。这在某些特殊布局中需要跳过前几条记录时非常实用。

其他辅助参数

• all：获取所有层级的分类 当all=true时，categoryList会获取指定moduleId下的所有分类，无论其层级如何。这在需要全面展示所有分类，而不关心层级结构时非常有用。
• siteId：多站点数据调用 对于使用AnQiCMS多站点管理功能的用户，siteId参数允许我们指定从哪个站点获取分类数据。一般情况下，如果只管理一个站点，此参数无需填写。

循环遍历与数据访问

categoryList标签返回的是一个可循环的对象集合（通常命名为categories或您自定义的变量名）。我们使用{% for ... in ... %}循环来访问其中的每一个分类项。在循环体内，每个分类项通常被命名为item，并提供了多种字段供我们调用。

item 对象的常用字段：

• Id： 分类ID，唯一标识符。
• Title： 分类名称，用于在前端显示。
• Link： 分类对应的URL链接，方便跳转。
• Description： 分类简介或描述。
• ParentId： 父级分类的ID。
• Logo / Thumb： 分类的大图或缩略图地址，可用于分类导航的图标或背景。
• Spacer： 用于展示层级关系的缩进前缀（例如：--），配合多级分类显示效果。
• HasChildren： 布尔值，指示当前分类是否有子分类。这在构建动态菜单时非常有用。
• IsCurrent： 布尔值，指示当前分类是否为当前页面所在的分类。可用于高亮当前导航项。
• ArchiveCount： 当前分类下包含的文档数量。

实战应用示例

1. 获取“文章”模型下的所有顶级分类

以下代码将获取ID为1的内容模型（假设为“文章”模型）下的所有顶级分类，并将其名称和链接打印出来。

<nav class="main-categories">
    <h3>文章分类</h3>
    <ul>
        {% categoryList articleCategories with moduleId="1" parentId="0" %}
            {% for item in articleCategories %}
                <li {% if item.IsCurrent %}class="active"{% endif %}>
                    <a href="{{ item.Link }}">{{ item.Title }}</a>
                </li>
            {% endfor %}
        {% endcategoryList %}
    </ul>
</nav>

2. 实现多级分类导航（以“产品”模型为例）

这个例子展示了如何构建一个两级导航，其中顶级分类来自“产品”模型（假设moduleId="2"），并且在其下方显示其直接子分类。

<ul class="product-menu">
    {% categoryList productRootCategories with moduleId="2" parentId="0" %}
        {% for rootCategory in productRootCategories %}
            <li {% if rootCategory.IsCurrent %}class="active"{% endif %}>
                <a href="{{ rootCategory.Link }}">{{ rootCategory.Title }}</a>
                {% if rootCategory.HasChildren %}
                    <ul class="submenu">
                        {% categoryList productSubCategories with parentId=rootCategory.Id %}
                            {% for subCategory in productSubCategories %}
                                <li {% if subCategory.IsCurrent %}class="active"{% endif %}>
                                    <a href="{{ subCategory.Link }}">{{ subCategory.Title }}</a>
                                </li>
                            {% endfor %}
                        {% endcategoryList %}
                    </ul>
                {% endif %}
            </li>
        {% endfor %}
    {% endcategoryList %}
</ul>

3. 结合文档列表，实现分类下的内容展示

这个场景常见于首页或特定栏目页，需要显示每个分类以及该分类下的最新文档。假设我们有一个文章模型（moduleId="1"）。

<section class="latest-articles">
    <h2>最新文章</h2>
    {% categoryList mainArticleCategories with moduleId="1" parentId="0" %}
        {% for category in mainArticleCategories %}
            <div class="category-block">
                <h3><a href="{{ category.Link }}">{{ category.Title }}</a></h3>
                <ul class="article-list">
                    {% archiveList articlesInCategory with type="list" categoryId=category.Id limit="5" %}
                        {% for article in articlesInCategory %}
                            <li>
                                <a href="{{ article.Link }}">
                                    {% if article.Thumb %}<img src="{{ article.Thumb }}" alt="{{ article.Title }}" />{% endif %}
                                    <h4>{{ article.Title }}</h4>
                                    <p>{{ article.Description|truncatechars:80 }}</p>
                                    <span class="date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
                                </a>
                            </li>
                        {% endfor %}
                    {% else %}
                        <li>该分类下暂无文章。</li>
                    {% endarchiveList %}
                </ul>
            </div>
        {% endfor %}
    {% endcategoryList %}
</section>

总结

categoryList标签是AnQiCMS模板系统中一个功能强大且灵活的工具。通过精确