在构建网站时，清晰的分类结构是提升用户体验和内容可发现性的关键。AnQiCMS 凭借其灵活的内容模型和强大的模板引擎，让我们能够非常方便地在网站前端展示分类列表及其层级关系。今天，我们就来深入了解如何在 AnQiCMS 模板中实现这一功能。

认识 AnQiCMS 的分类列表标签：categoryList

AnQiCMS 模板基于 Go 语言的 Django 模板引擎语法，提供了直观且功能丰富的标签来操作数据。要显示分类列表，我们主要会用到 categoryList 这个标签。这个标签能帮助我们获取文章或产品等内容模型的分类数据，并按照我们期望的方式进行展示。

让我们从一个简单的例子开始。假设我们想要在网站侧边栏显示所有顶级文章分类，我们可以这样编写模板代码：

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

在这段代码中：

  • {% categoryList categories ... %}：我们定义了一个名为 categories 的变量，它将承载从数据库获取到的分类列表数据。
  • moduleId="1"：这是非常关键的一个参数。在 AnQiCMS 中，每个分类都隶属于一个特定的内容模型（例如，文章模型通常为 1，产品模型可能为 2）。通过指定 moduleId，我们确保只获取到所需内容模型的分类。
  • parentId="0"：这个参数告诉系统我们只想要获取顶级分类。如果想获取某个特定分类下的子分类，我们则会传递该父分类的 Id。
  • {% for item in categories %}：我们使用 for 循环来遍历 categories 变量中的每一个分类项。
  • {{ item.Link }}：这会输出当前分类的 URL 链接。
  • {{ item.Title }}：这会显示当前分类的名称。

优雅地展示多级分类层级

如果我们的网站分类结构有层级关系，比如“新闻动态”下有“公司新闻”和“行业资讯”，我们同样可以通过 categoryList 标签轻松实现多级嵌套展示。

以下是一个展示两级分类的例子：

{% categoryList mainCategories with moduleId="1" parentId="0" %}
    <ul class="main-nav">
        {% for mainItem in mainCategories %}
        <li class="main-nav-item">
            <a href="{{ mainItem.Link }}">{{ mainItem.Title }}</a>
            {% if mainItem.HasChildren %}
            <ul class="sub-nav">
                {% categoryList subCategories with parentId=mainItem.Id %}
                    {% for subItem in subCategories %}
                    <li class="sub-nav-item">
                        <a href="{{ subItem.Link }}">{{ subItem.Title }}</a>
                        {# 如果需要更多层级，可以继续嵌套 categoryList 标签 #}
                    </li>
                    {% endfor %}
                {% endcategoryList %}
            </ul>
            {% endif %}
        </li>
        {% endfor %}
    </ul>
{% endcategoryList %}

这里我们引入了几个新的概念：

  • {% if mainItem.HasChildren %}：这是一个非常有用的条件判断。HasChildren 属性会返回一个布尔值，告诉我们当前分类是否有子分类。只有当一个分类有子分类时，我们才渲染它的子菜单，这样可以避免生成空的 <ul> 标签，使页面结构更干净。
  • parentId=mainItem.Id：在内层循环中，我们将外层循环 mainItem 的 Id 作为 parentId 传递给 categoryList 标签，这样就能准确地获取到 mainItem 的直接子分类。
  • item.Spacer：AnQiCMS 还提供了一个 Spacer 字段，它会根据分类层级自动生成前缀（例如 &nbsp;&nbsp;|--），在管理后台或某些特定展示场景下，可以帮助我们直观地看到分类的层级深度。在前端展示时，通常会通过 CSS 来控制缩进和层级样式，但 Spacer 提供了一个备用选项，记得使用 |safe 过滤器来确保 HTML 实体被正确解析。

在分类列表中同时展示其下文档

有时候，我们不仅想显示分类本身，还想在每个分类下展示一些最新的文章或产品。AnQiCMS 同样允许我们灵活地组合 categoryList 和 archiveList 标签来实现这一需求。

{% categoryList categories with moduleId="1" parentId="0" %}
    <div class="category-block">
        {% for catItem in categories %}
        <h3><a href="{{ catItem.Link }}">{{ catItem.Title }}</a></h3>
        <ul class="latest-articles">
            {% archiveList archives with type="list" categoryId=catItem.Id limit="5" %}
                {% for article in archives %}
                <li>
                    <a href="{{ article.Link }}">
                        <h4>{{ article.Title }}</h4>
                        <p>{{ article.Description|truncatechars:100 }}</p>
                    </a>
                </li>
                {% empty %}
                <li>当前分类暂无文章。</li>
                {% endfor %}
            {% endarchiveList %}
        </ul>
        {% endfor %}
    </div>
{% endcategoryList %}

在这个例子中：

  • 我们在每个 catItem 循环内部又嵌套了一个 archiveList 标签。
  • categoryId=catItem.Id：这里我们将当前分类 catItem 的 Id 传递给 archiveList，确保只获取到该分类下的文章。
  • limit="5"：限制每个分类只显示最新的 5 篇文章。
  • type="list"：表示我们只需要一个简单的列表，而不是分页列表。
  • {{ article.Description|truncatechars:100 }}：使用了 truncatechars 过滤器来截取文章描述的前 100 个字符，并自动添加省略号，保持页面整洁。

总结

AnQiCMS 的 categoryList 标签及其丰富的参数和返回属性，为我们提供了极大的灵活性来构建各种复杂的分类展示。无论是简单的扁平列表，还是多层级的嵌套菜单，甚至是在分类中直接嵌入相关内容，都可以通过直观的模板语法轻松实现。合理运用这些功能，将帮助我们打造结构清晰、内容丰富且用户友好的网站。在实际操作中，别忘了多查看 AnQiCMS 官方文档中的标签详情，那里会有更详尽的参数说明和高级用法，助力你实现更多创意。

常见问题 (FAQ)

1. 为什么我的分类列表代码已经写了，但前端页面上没有任何内容显示？

这通常有几个原因： 首先，请检查 moduleId 参数是否正确。AnQiCMS 中的分类是与特定的内容模型（如文章、产品）绑定的，如果 moduleId 不正确或没有文章/产品分类，列表自然不会显示。其次，确认你指定的 parentId（如果使用了）下确实存在子分类。最后，检查你的 AnQiCMS 后台是否已经创建了对应的分类数据。

2. 我想在导航栏显示分类，但 AnQiCMS 的 navList 标签也可以做导航，我应该用哪一个？

navList 标签是专门用于展示后台“网站导航设置”中配置的导航菜单的。它更侧重于网站的全局导航结构，可能包含分类、单页面或外部链接的组合。而 categoryList 标签则专注于从内容模型中获取和展示纯粹的分类数据。如果你需要一个根据后台分类数据自动生成的导航（例如，显示所有文章分类），categoryList 更合适；如果你希望导航菜单内容更灵活，可以在后台手动拖拽调整顺序，并且包含多种链接类型，那么 navList 会是更好的选择。两者可以结合使用，例如在 navList 的某个菜单项下嵌套 categoryList 来展示子分类。

3. 如何为不同层级的分类设置不同的样式（比如一级分类用粗体，二级分类用斜体）？

在 categoryList 的 for 循环中，你可以利用 item.ParentId 来判断当前分类的层级。例如，如果 item.ParentId == 0，它就是顶级分类；如果 item.ParentId > 0，它就是子分类。你还可以结合 CSS 类名来实现差异化样式。例如：

{% categoryList categories with moduleId="1" %}
    <ul>
        {% for item in categories %}
            <li class="{% if item.ParentId == 0 %}level-1{% else %}level-2{% endif %}">
                <a href="{{ item.Link }}">{{ item.Title }}</a>
                {# ... 更多嵌套分类 ... #}
            </li>
        {% endfor %}
    </ul>
{% endcategoryList %}

通过这种方式，你可以用 level-1 和 level-2 等 CSS 类来定义不同层级的样式。