在安企CMS的灵活内容管理世界里，模板标签是我们与数据交互的桥梁。其中，categoryList标签无疑是构建网站导航和内容列表的核心工具之一。然而，资深运营者们常会遇到这样一个场景：当网站处于某个具体分类页面时，categoryList标签会“智能”地读取当前分类的ID，并以此为上下文进行数据展示。这在很多情况下是极其便利的，例如展示当前分类的子分类或同级分类。
但想象一下，您的网站需要一个固定不变的顶部主导航，它始终只展示网站的顶级分类，而无论用户当前浏览的是哪篇文章或哪个子分类。此时，categoryList的这份“智能”反而成了困扰。如何才能让它“放下包袱”，强制只显示那些位于最顶层的分类呢？今天，我们就来深入探讨这个问题，并为您提供行之有效的解决方案。
categoryList的“智能”与困境
安企CMS的categoryList标签，其设计初衷是为了让模板开发者能够轻松构建出上下文感知的分类列表。默认情况下，如果您在分类详情页或文章详情页调用categoryList时，没有明确指定categoryId参数，它便会默认将当前页面的分类ID作为筛选条件，这使得列表能够自动适应当前页面的内容，显示其相关的子分类或同级分类。这种行为在多数动态内容展示场景下都是高效且便捷的。
然而，正如前面提到的固定主导航需求，或者需要在一个完全不相关的页面（比如首页）展示某个内容模型的所有顶级分类时，这种默认行为就会变得不合时宜。我们需要一种方法，明确告诉categoryList：“请忽略当前页面的分类ID，我只想要最顶层的分类。”
揭秘解决方案：强制指定顶级分类
安企CMS的模板标签提供了足够的灵活性来应对这类需求。要实现“强制只显示顶级分类”的目标，我们需要巧妙地结合使用categoryId、parentId和moduleId这三个参数。
categoryId="0"：斩断与当前页面上下文的联系categoryList标签的categoryId参数，顾名思义，是用来指定要获取哪个分类下的内容。当您将其明确设置为"0"时，就等于向系统发出了一个清晰的指令：“请不要尝试从当前页面环境中自动获取任何分类ID作为筛选条件！” 这就有效地阻止了categoryList的默认“智能”行为。parentId="0"：锁定目标为最顶层分类parentId参数是用来指定要获取哪个父级分类下的子分类。将其设置为"0"，意味着您正在明确请求那些没有父级分类的分类，即我们常说的顶级分类。moduleId：限定分类的所属范围 当您使用parentId="0"来获取顶级分类时，系统需要知道您想获取的是哪个内容模型（例如“文章模型”或“产品模型”）下的顶级分类。因为不同内容模型可能有各自独立的分类体系。因此，moduleId参数在这时成为了必不可少的伙伴。您需要根据实际情况，提供您想展示的顶级分类所属的内容模型ID（例如，文章模型ID通常为1，产品模型ID通常为2）。
将这三个参数结合起来，我们就能精确地指示categoryList标签，实现我们想要的效果。
实战演练：一步步实现
让我们通过一个具体的例子来演示如何操作。假设您希望在网站的头部导航区域，始终展示“文章模型”下的所有顶级分类。
首先，在您的模板文件（例如partial/header.html或base.html中引用header的部分）里，您可能会看到类似默认的categoryList调用方式（如果存在的话）：
{# 默认或不带参数的categoryList调用，可能受当前页面分类ID影响 #}
{% categoryList categories with moduleId="1" %}
<ul>
{% for item in categories %}
<li><a href="{{item.Link}}">{{item.Title}}</a></li>
{% endfor %}
</ul>
{% endcategoryList %}
要改造它，使其强制只显示“文章模型”（假设其moduleId为1）的顶级分类，您可以这样修改：
{# 强制显示文章模型的顶级分类，忽略当前页面上下文 #}
{% categoryList topLevelCategories with moduleId="1" parentId="0" categoryId="0" %}
<nav class="main-navigation">
<ul>
{% for category in topLevelCategories %}
<li><a href="{{category.Link}}">{{category.Title}}</a></li>
{% endfor %}
</ul>
</nav>
{% endcategoryList %}
在上面的代码中：
topLevelCategories是我们为获取到的顶级分类列表定义的变量名，您可以随意命名。moduleId="1"明确指定了我们要获取的是文章模型的分类。如果您的顶级分类属于产品模型，则可能需要将moduleId设置为2，依此类推。parentId="0"确保我们只获取那些没有父级分类的顶层分类。categoryId="0"是关键，它告诉categoryList标签不要自动继承当前页面的分类ID，从而避免了不必要的上下文干扰。
通过这样的组合，无论用户当前访问的是哪一个具体分类下的文章，甚至是单页面或搜索结果页，这段代码都会稳定地展示文章模型的全部顶级分类，实现您的固定主导航需求。
深入理解：参数的搭配与意义
理解这些参数的搭配是至关重要的：
categoryId="0"的作用是解耦。它让categoryList在进行分类筛选时，不再依赖于URL或页面环境中可能存在的分类ID，而是完全听从您在标签中设定的其他筛选条件。parentId="0"的作用是筛选。它精确地过滤出所有ParentId为0的分类，这些分类正是我们在网站结构中定义的顶级分类。moduleId的作用是限定范围。由于不同模型下的分类是独立的，moduleId告诉系统应该在哪个模型的分类数据中进行筛选。
这三个参数协同工作，确保了categoryList在脱离页面上下文的情况下，依然能够准确地找出并展示您所期望的顶级分类列表。
应用场景拓展
这种强制显示顶级分类的技巧，不仅适用于主导航：
- 侧边栏的“全部栏目”：在任何页面，侧边栏可能都需要一个固定的入口，展示某个内容模型的全部顶级分类。
- 首页分类入口：首页需要展示各内容模型的入口时，通常也只展示顶级分类。
- 页脚导航：页脚有时也会包含一些主要的分类链接，这些链接通常也都是指向顶级分类。
掌握这一技巧，能让您在安企CMS的模板开发中更加游刃有余，构建出更加灵活和稳健的网站结构。
总结
安企CMS的categoryList标签虽然默认具有上下文感知能力，但在需要固定显示顶级分类的场景下，通过将categoryId和parentId均设置为"0"，并结合moduleId来指定内容模型，我们可以轻松地覆盖其默认行为，实现精准的分类列表展示。这不仅提升了模板的通用性，也为网站的结构布局带来了更大的自由度。
常见问题 (FAQ)
Q1: categoryList为什么默认会读取当前页面的分类ID？这种设计有什么好处？
A1: categoryList默认读取当前页面分类ID的设计是为了提高模板的灵活性和开发效率。在许多情况下，您可能希望在分类页面或文章详情页显示与当前内容相关的子分类或同级分类（例如，当用户在“新闻中心”下浏览某篇文章时，侧边栏自动显示“国内新闻”、“国际新闻”等）。通过自动继承当前页面的分类ID，开发者无需在每个页面手动传入参数，系统就能智能地根据上下文调整列表内容，大大简化了动态导航和内容块的实现。
Q2: 除了顶级分类，我能否强制显示某个特定父分类下的所有子分类，同时忽略当前页面ID？
A2: 当然可以。您只需要将parentId参数设置为您想显示其子分类的父分类ID即可，并同时将categoryId="0"以忽略当前页面上下文，再辅以moduleId来限定内容模型。例如，要显示ID为5的父分类下的所有子分类（文章模型），您可以这样写：
{% categoryList subCategories with moduleId="1" parentId="5" categoryId="0" %}。
Q3: 如果我只想显示某个特定内容模型的分类，但不需要强制它们是顶级分类，或者需要它们是多级嵌套的，应该怎么做？
A3: 如果您只想限定分类的所属内容模型，但不限制其层级，并且希望保留多级嵌套的特性，您只需指定moduleId参数，并可以省略parentId和categoryId="0"。例如，要获取“产品模型”（假设moduleId="2")下的所有分类（包括多级嵌套），您可以这样调用：
{% categoryList productCategories with moduleId="2" %}。然后，您可以在for循环中利用item.HasChildren和递归categoryList来构建多级嵌套菜单。