`categoryList`标签如何获取并显示AnQiCMS文章或产品分类的列表？

在AnQiCMS中构建一个功能完善、内容丰富的网站，分类是组织内容不可或缺的一部分。无论是展示文章、产品、服务，还是搭建导航菜单，清晰的分类结构都能极大提升用户体验和网站的可维护性。今天，我们就来深入了解AnQiCMS中一个非常实用且灵活的标签——categoryList，它能帮助您轻松获取并显示文章或产品分类的列表。

categoryList标签是AnQiCMS模板引擎中的一把利器，它的主要作用是根据您指定的条件，从数据库中提取出符合要求的分类数据，并以列表的形式供您在前端页面展示。通过合理运用这个标签，您可以搭建出各种复杂的分类导航、内容聚合模块，让网站的内容组织变得井井有条。

categoryList标签概览：轻松驾驭分类数据

这个标签的基本使用格式非常直观：

{% categoryList 变量名称 with 参数 %}
    {# 在这里循环输出分类数据 #}
{% endcategoryList %}

您需要为分类列表指定一个变量名称（例如categories、productCategories等），这样在标签内部，您就可以通过这个变量来访问每一个分类的具体信息。with关键字后面跟着一系列的参数，这些参数就是您筛选和定制分类列表的关键。

接下来，我们详细解读categoryList标签的几个核心参数，让您能够根据实际需求灵活地获取分类数据。

核心参数解析：定制您的分类列表

  1. moduleId：指定内容模型，精准定位分类来源 在AnQiCMS中，内容可以归属于不同的“模型”，比如文章模型（通常ID为1）、产品模型（通常ID为2）等。moduleId参数就是告诉categoryList您想获取哪个模型下的分类。

    • 示例：
      • moduleId="1"：获取所有文章分类。
      • moduleId="2"：获取所有产品分类。

    如果您不确定某个模型的ID，可以在AnQiCMS后台的“内容管理” -> “内容模型”中查看。

  2. parentId：构建层级关系，灵活控制分类深度 分类往往是多层级的，parentId参数正是用来控制您要获取的分类在层级结构中的位置。

    • parentId="0"：获取顶级分类 这是最常见的用法，例如用于网站的主导航菜单。它会列出指定模型下的所有一级分类。
      • 示例：{% categoryList categories with moduleId="1" parentId="0" %}
    • 不指定parentId：获取当前分类的下级分类 当您在某个分类详情页或分类列表页时，不指定parentId会自动获取当前分类的所有直接子分类。这非常适合构建侧边栏的二级/三级导航。
      • 示例：{% categoryList subCategories %}（假设当前页面是一个分类页面）
    • parentId="parent"：获取当前分类的兄弟分类 这个参数在某些特定场景下非常有用，比如您想在某个分类页面显示其同级的所有分类。这个参数仅在当前页面是分类列表页或详情页时有效。
      • 示例：{% categoryList brotherCategories with parentId="parent" %}

  3. all：获取所有分类，不拘泥于层级 如果您需要列出指定模型下的所有分类，无论它们处于哪个层级，都可以使用all=true。这在某些聚合页面或全局站点地图中可能会用到。

    • 示例：{% categoryList allCategories with moduleId="1" all=true %}

  4. limit：控制显示数量，优化页面布局 有时您不需要显示所有分类，而只想显示前几个热门分类或指定数量的分类。limit参数可以帮助您实现这个目标。它支持两种模式：

    • 单数字：limit="10"，表示显示前10个分类。
    • “偏移量,数量”：limit="2,5"，表示从第2个分类开始（索引从0开始，所以实际是第3个），显示5个分类。
    • 示例：{% categoryList topCategories with moduleId="1" parentId="0" limit="5" %}

  5. siteId：多站点场景的应用 如果您的AnQiCMS部署了多个站点，并且您希望在一个站点中调用另一个站点的分类数据，可以通过siteId参数来指定目标站点的ID。这在需要跨站点数据整合时非常有用。一般情况下，如果您只有一个站点，可以忽略此参数。

    • 示例：{% categoryList otherSiteCategories with moduleId="1" parentId="0" siteId="2" %}

掌握分类数据：item变量中的宝藏

当categoryList标签成功获取到分类列表后，您可以通过循环遍历变量名称（如categories）来访问每个分类的详细信息。在循环内部，每个分类对象通常命名为item（您可以自定义，如category），它包含了丰富的字段，供您在模板中展示：

  • item.Id：分类的唯一标识ID。
  • item.Title：分类的名称，这是最常显示的内容。
  • item.Link：分类的访问链接，用于构建可点击的导航。
  • item.Description：分类的简短描述，可能用于SEO或在分类列表中展示。
  • item.Content：分类的详细内容（如果后台有填写），可能会在分类详情页显示。
  • item.ParentId：当前分类的上级分类ID，用于判断层级关系。
  • item.Logo：分类的大图或Banner图地址。
  • item.Thumb：分类的缩略图地址，常用于在列表中显示小图标或小图。
  • item.Spacer：一个特殊的前缀，通常用于在多级分类列表中生成缩进，以视觉上区分层级。
  • item.HasChildren：一个布尔值（true或false），指示当前分类是否有子分类。这对于构建动态菜单或根据是否有子分类显示不同内容非常关键。
  • item.IsCurrent：一个布尔值，指示当前分类是否是当前页面所在的分类。常用于在导航中添加active类名，高亮显示。
  • item.ArchiveCount：当前分类下包含的文档（文章或产品）数量。

实战演练：categoryList的妙用

掌握了参数和字段后，我们来看看一些常见的实战场景：

1. 展示网站顶部主导航（顶级分类）

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

这个例子展示了如何获取文章模型下的所有顶级分类，并在当前分类时添加active样式。

2. 构建侧边栏多级分类菜单

<aside class="sidebar-nav">
    <h3>产品分类</h3>
    <ul>
        {% categoryList productMainCategories with moduleId="2" parentId="0" %}
            {% for mainCat in productMainCategories %}
                <li class="{% if mainCat.IsCurrent %}active{% endif %}">
                    <a href="{{ mainCat.Link }}">{{ mainCat.Title }}</a>
                    {% if mainCat.HasChildren %}
                        <ul>
                            {% categoryList subCategories with parentId=mainCat.Id %} {# 获取当前主分类的子分类 #}
                                {% for subCat in subCategories %}
                                    <li class="{% if subCat.IsCurrent %}active{% endif %}">
                                        <a href="{{ subCat.Link }}">{{ subCat.Title }}</a>
                                    </li>
                                {% endfor %}
                            {% endcategoryList %}
                        </ul>
                    {% endif %}
                </li>
            {% endfor %}
        {% endcategoryList %}
    </ul>
</aside>

这个例子利用了HasChildren和嵌套的categoryList标签，动态地构建了两级产品分类菜单。

3. 在首页显示不同分类下的最新文章或产品

这是一种常见的内容聚合方式，让访问者一眼看到网站的最新动态。

{% categoryList featuredCategories with moduleId="1" parentId="0" limit="3" %}
    {% for cat in featuredCategories %}
        <section class="category-section">
            <h3><a href="{{ cat.Link }}">{{ cat.Title }}</a></h3>
            <p>{{ cat.Description }}</p>
            <ul class="article-list">
                {% archiveList latestArticles with type="list" categoryId=cat.Id limit="5" %}
                    {% for article in latestArticles %}
                        <li>
                            <a href="{{ article.Link }}">
                                <img src="{{ article.Thumb }}" alt="{{ article.Title }}">
                                <h4>{{ article.Title }}</h4>
                                <time>{{ stampToDate(article.CreatedTime, "2006-01-02") }}</time>
                            </a>
                        </li>
                    {% empty %}
                        <li>该分类暂无文章。</li>
                    {% endfor %}
                {% endarchiveList %}
            </ul>
        </section>
    {% endfor %}
{% endcategoryList %}

这个示例展示了如何先获取3个顶级文章分类，然后通过archiveList标签在每个分类下获取最新的5篇文章。

一些小提示：

  • 标签闭合：请务必确保{% categoryList %}标签与{% endcategoryList %}成对出现，否则会导致模板解析错误。
  • 变量名一致：在{% categoryList 变量名称 %}中定义的变量名，应与内部{% for %}循环或直接访问字段时使用的变量名保持一致。
  • 结合categoryDetail：如果需要获取某个特定分类的更多详细信息，例如其Banner图或自定义字段，可以在循环内部结合使用categoryDetail标签，传入item.Id即可。
  • 性能考量：虽然categoryList非常灵活，但在一个页面中过度嵌套或大量调用可能会影响页面加载速度。在设计复杂结构时，请注意优化查询和页面渲染效率。

通过以上介绍，相信您已经对AnQiCMS的categoryList