作为一名深谙AnQiCMS运作之道的网站运营人员，我理解您在追求内容展示个性化和用户体验优化方面的需求。自定义分类下的文档列表模板是实现这一目标的关键步骤。AnQiCMS提供了灵活的模板机制，让您可以根据特定分类的内容特色，呈现独特的列表布局。
AnQiCMS的模板机制概述
AnQiCMS采用类似Django模板引擎的语法，以.html作为模板文件后缀，并将它们统一存放在站点的/template目录下。模板中的变量使用双花括号{{变量}}定义，而条件判断、循环控制等逻辑标签则使用单花括号和百分号{% 标签 %}。这种设计理念使得模板结构清晰，易于理解和定制。
在AnQiCMS中，模板通常会通过extends标签继承一个基础骨架模板（例如base.html或bash.html），以确保页面结构的一致性，并在不同的block区域实现内容的差异化。这种继承关系极大地提升了模板的复用性和维护效率。
自定义特定分类下文档列表模板的两种方法
在AnQiCMS中，您可以通过两种主要方式来实现针对特定分类的文档列表模板定制，这两种方法各有侧重，可以根据您的具体需求选择使用。
方法一：通过命名约定自动应用模板
AnQiCMS内置了一套智能的模板命名约定机制，允许您为特定的分类列表创建定制模板，系统会根据约定的文件名自动识别并应用。
具体的命名格式是：{模型table}/list-{分类id}.html
要采用这种方式，您需要完成以下步骤：
- 确定模型表名（
{模型table}）：每个内容模型在AnQiCMS中都有一个对应的表名。例如，如果您要定制“文章”模型的某个分类列表，其模型表名通常是article。您可以在AnQiCMS后台的“内容模型”管理界面中查看到每个模型的“模型表名”或“URL别名”。 - 获取分类ID（
{分类id}）：在AnQiCMS后台的“文档分类”管理界面中，找到您想要定制的特定分类。每个分类都会有一个唯一的数字ID。 - 创建模板文件：在您当前使用的模板主题目录下（例如
/template/default），找到或创建对应的模型文件夹（例如article/），然后在此文件夹内创建一个名为list-{分类id}.html的文件。例如，如果您的文章模型表名是article，且目标分类ID是10，那么模板文件路径将是article/list-10.html。
一旦文件创建并放置在正确的位置，当用户访问ID为10的分类列表页时，AnQiCMS将自动加载并应用article/list-10.html这个模板。这种方法适用于需要为少数几个重要分类进行深度定制的场景，因为它直接关联到分类ID，实现了一对一的精确匹配。
方法二：通过后台分类设置指定自定义模板
AnQiCMS还提供了在后台为每个分类手动指定自定义模板文件的灵活性。这种方法提供了更大的文件名自由度，并且便于在后台统一管理。
操作步骤如下：
- 准备自定义模板文件：在您的模板主题目录下，您可以创建一个自定义的模板文件，例如，您可以将其命名为
special_category_list.html，并放置在如article/目录下，形成路径article/special_category_list.html。或者，为了更好的组织，您也可以将其放置在其他自定义路径下，只要确保路径是相对于模板主题根目录即可。 - 编辑分类设置：登录AnQiCMS后台，导航至“内容管理”下的“文档分类”页面。找到您想要定制的特定分类，点击“编辑”按钮。
- 指定“分类模板”：在分类编辑页面的“其他参数”部分，您会找到一个名为“分类模板”的输入框。在这里，填入您自定义模板文件的相对路径和文件名。例如，如果您创建的文件是
article/special_category_list.html，您就在此处填入article/special_category_list.html。
填写并保存后，当用户访问这个分类的列表页时，AnQiCMS将优先使用您在后台指定的这个自定义模板。这种方式的优点是文件名不受分类ID的限制，更具描述性，并且可以通过后台界面集中管理和调整。同时，如果模板文件不存在，AnQiCMS会回退到默认的列表模板，避免页面打不开。
创建自定义模板的内容
无论您选择哪种方式，自定义模板文件的核心内容是相似的。它需要包含页面结构，并利用AnQiCMS的模板标签来动态获取和展示数据。
一个典型的分类列表模板内容大致如下：
{% extends "base.html" %} {# 继承您的基础模板 #}
{% block title %}
<title>{% tdk with name="Title" siteName=true %}</title> {# 使用TDK标签获取当前页面标题 #}
{% endblock %}
{% block content %}
<div class="category-list-header">
{# 获取当前分类的详细信息 #}
{% categoryDetail currentCategory with name="Title" %}
<h1>{{ currentCategory }}</h1>
{% categoryDetail categoryDesc with name="Description" %}
<p>{{ categoryDesc }}</p>
{# 如果分类有Banner图，可以这样显示 #}
{% categoryDetail bannerImages with name="Images" %}
{% if bannerImages %}
{% set pageBanner = bannerImages[0] %}
<div class="category-banner" style="background-image: url({{pageBanner}});"></div>
{% endif %}
</div>
<div class="document-list-container">
{# 使用 archiveList 标签获取当前分类下的文档列表，并启用分页 #}
{% archiveList archives with type="page" limit="10" %}
{% for item in archives %}
<div class="document-item">
<a href="{{item.Link}}">
{% if item.Thumb %}<img src="{{item.Thumb}}" alt="{{item.Title}}">{% endif %}
<h2>{{item.Title}}</h2>
<p>{{item.Description}}</p>
<div class="meta">
<span>发布日期: {{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
<span>浏览量: {{item.Views}}</span>
</div>
</a>
</div>
{% empty %}
<p>该分类下暂无文档。</p>
{% endfor %}
{% endarchiveList %}
</div>
<div class="pagination-area">
{# 使用 pagination 标签展示分页导航 #}
{% pagination pages with show="5" %}
<nav>
<ul>
{% if pages.FirstPage %}<li class="{% if pages.FirstPage.IsCurrent %}active{% endif %}"><a href="{{pages.FirstPage.Link}}">{{pages.FirstPage.Name}}</a></li>{% endif %}
{% if pages.PrevPage %}<li class="prev"><a href="{{pages.PrevPage.Link}}">{{pages.PrevPage.Name}}</a></li>{% endif %}
{% for item in pages.Pages %}<li class="{% if item.IsCurrent %}active{% endif %}"><a href="{{item.Link}}">{{item.Name}}</a></li>{% endfor %}
{% if pages.NextPage %}<li class="next"><a href="{{pages.NextPage.Link}}">{{pages.NextPage.Name}}</a></li>{% endif %}
{% if pages.LastPage %}<li class="{% if pages.LastPage.IsCurrent %}active{% endif %}"><a href="{{pages.LastPage.Link}}">{{pages.LastPage.Name}}</a></li>{% endif %}
</ul>
</nav>
{% endpagination %}
</div>
{% endblock %}
上述代码示例中，{% extends "base.html" %}声明了该模板继承自base.html，{% block title %}和{% block content %}则重写了基础模板中的对应内容区域。tdk标签用于获取SEO标题，categoryDetail标签用于获取当前分类的标题、描述等信息，而archiveList标签则负责获取分类下的文档列表，并通过type="page"参数启用分页功能。最后，pagination标签生成了页码导航。
**实践与注意事项
在自定义模板时，请务必注意以下几点：
- 路径与命名：确保您的自定义模板文件位于当前使用的模板主题目录下，并且文件名或后台设置的路径准确无误。
- 模板继承：善用
{% extends %}和{% block %}标签，这有助于保持代码整洁、模块化，并降低维护成本。将页面的通用结构放在一个基础模板中，然后在具体页面模板中重写需要变化的部分。 - 标签使用：熟悉AnQiCMS提供的各种模板标签（如
archiveList,categoryDetail,pagination,tdk等），它们是获取和展示数据的关键。务必参考官方文档中的标签用法说明，确保参数正确。 - 缓存清理：在修改模板文件后，有时前端页面可能不会立即更新。这通常是由于系统缓存或浏览器缓存造成的。请尝试在AnQiCMS后台执行“更新缓存”操作，并清除浏览器缓存（Ctrl+F5），以确保您的更改生效。
- 错误检查：如果页面显示异常，首先检查服务器错误日志和AnQiCMS后台的日志记录，通常能提供有价值的线索。模板语法错误也可能导致页面无法正常渲染。
通过上述方法，您可以为AnQiCMS网站的特定分类打造独一无二的文档列表展示，从而提升内容运营的精细化程度和用户体验。
常见问题 (FAQ)
1. 我创建了自定义模板文件，但在后台选择后或者按命名约定放置后，页面仍然显示默认模板内容，或者页面报错，这是什么原因？
这通常是由以下几个原因导致的：
- 文件路径或文件名不正确：请仔细核对自定义模板文件是否位于当前启用的模板主题目录下，以及文件名是否与后台设置或命名约定（例如
{模型table}/list-{分类id}.html）完全匹配。即使是大小写错误也可能导致系统无法识别。 - AnQiCMS缓存未更新：在修改或添加模板文件后，AnQiCMS可能存在页面缓存。请登录后台，点击“更新缓存”功能，然后尝试清除浏览器缓存（Ctrl+F5）再访问页面。
- 模板语法错误：如果自定义模板文件中存在语法错误（例如标签未闭合、变量名拼写错误等），系统可能无法正确解析该模板，导致页面报错或回退到默认模板。请检查服务器错误日志获取详细错误信息。
2. 我可以在自定义分类列表模板中获取当前分类以外的其他分类或文档信息吗？
完全可以。AnQiCMS的模板标签设计具有很高的灵活性。在您的自定义分类列表模板中，您可以继续使用categoryList标签来获取其他分类列表（例如，侧边栏显示兄弟分类或子分类），也可以使用archiveList标签来获取其他分类下的热门文档、推荐文档等，只需要在标签中指定相应的moduleId、categoryId、flag等参数即可。例如，{% categoryList subCategories with parentId=currentCategory.Id %}可以获取当前分类的子分类。
3. 自定义模板中的CSS和JavaScript文件应该如何引用？
在自定义模板中引用CSS和JavaScript文件时，建议使用{% system with name="TemplateUrl" %}标签来获取当前模板主题的静态资源根路径。例如，如果您的CSS文件位于/template/您的主题名/static/css/style.css，您可以在模板中使用：
<link href="{% system with name="TemplateUrl" %}/static/css/style.css" rel="stylesheet">
这样做的好处是，即使您更换了模板主题名称，只要静态资源结构不变，引用路径也无需修改，系统会自动适应，提升了模板的通用