AnQiCMS 作为一个以其高效、灵活著称的内容管理系统，在模板制作方面也有一套清晰的约定，旨在帮助开发者和运营者构建结构清晰、易于维护的网站。理解这些约定，是高效利用 AnQiCMS 进行网站定制和内容展示的关键一步。

模板文件的核心约定

AnQiCMS 的模板文件，统一采用 .html 作为后缀名。这一约定让文件类型一目了然，也有助于编辑器进行语法高亮和智能提示。所有模板文件都集中存放在系统根目录下的 /template 文件夹中，每套独立的模板则在这个总目录下拥有自己的专属子目录。举例来说，如果你有两套模板，一套名为 default，另一套名为 custom，那么它们将分别位于 /template/default/ 和 /template/custom/。

除了模板文件本身，模板中还会用到图片、CSS 样式、JavaScript 脚本等静态资源。这些文件则集中管理在 /public/static/ 目录下，与模板文件分开放置，这样做有利于静态资源的管理、CDN 加速以及与模板逻辑的分离。

在模板制作时，统一采用 UTF8 编码是基础要求。如果模板文件使用其他编码，可能会导致页面出现乱码，影响用户体验。因此，无论是通过代码编辑器还是其他工具编辑模板，务必确保文件以 UTF8 格式保存。

AnQiCMS 模板引擎的语法风格，借鉴了 Django 模板引擎，并与 Blade 语法有相似之处，因此对于熟悉这些语法的开发者而言，上手会非常容易。它使用双花括号 {{变量}} 来输出变量，而条件判断、循环控制等逻辑标签则使用单花括号和百分号 {% 标签 %} 定义，并且这些逻辑标签通常需要成对出现，例如 {% if 条件 %}...{% endif %}。变量的命名约定也需留意，系统推荐使用驼峰命名法（即每个单词首字母大写，如 archive.Id、archive.Title），部分特殊规定的除外。

模板目录的组织结构与配置文件

每套模板的目录内，都会有一个 config.json 文件，它是模板的“身份证”，包含了模板的基本信息和配置。这个文件描述了模板的名称、版本、作者、描述等元数据，其中最重要的字段之一是 template_type，它定义了模板的类型：0 为自适应，1 为代码适配，2 为电脑+手机独立模式。另一个关键字段是 status，它指示了模板是否正在被使用，同一时间只能有一套模板的 status 值为 1。

为了适应不同的开发习惯和项目规模，AnQiCMS 提供了两种主要的模板文件组织模式：

  1. 文件夹组织模式： 这种模式将不同类型的页面模板归类到各自的文件夹中，结构清晰，便于查找和管理。例如：

    • 公共代码（如页头、页脚）通常放在 bash.html 文件中，供其他模板引用。
    • 代码片段（如侧边栏、面包屑）则存放在 partial/ 目录下。
    • 首页模板通常是 index/index.html。
    • 文章、产品等内容模型的首页、详情页和列表页会根据模型表名进行组织，例如 {模型table}/index.html（模型首页）、{模型table}/detail.html（文档详情页）、{模型table}/list.html（文档列表页）。
    • 其他特殊页面如评论列表页 (comment/list.html)、在线留言页 (guestbook/index.html)、单页面详情页 (page/detail.html)、搜索页 (search/index.html)、标签首页 (tag/index.html)、以及错误页面 (errors/404.html, errors/500.html, errors/close.html) 也有其对应的目录和文件名。

  2. 扁平化文件组织模式： 另一种是扁平化文件组织模式，顾名思义，这种模式下大部分模板文件都直接放置在模板根目录下，通过文件名前缀来区分类型。例如：

    • 公共代码和代码片段的约定与文件夹模式相同（bash.html 和 partial/）。
    • 首页模板是 index.html。
    • 内容模型相关的模板则会加上模型表名的前缀，例如 {模型table}_index.html、{模型table}_detail.html、{模型table}_list.html。
    • 其他特殊页面的模板文件名则相应变为 comment_list.html、guestbook.html、page.html、search.html、tag_index.html、errors_404.html 等。

值得注意的是，无论采用哪种组织模式，如果网站需要支持移动端模板，都会在模板根目录下创建一个 mobile/ 子目录，并在其中重复上述的文件组织结构和命名约定，以提供移动设备专用的页面布局。

具体的模板命名约定与自定义灵活性

AnQiCMS 为一些核心页面类型设定了更具体的默认命名约定，这些约定能够让系统自动识别并应用模板，大大简化了后台配置。

  • 文档默认自定义模板：可以命名为 {模型table}/{文档id}.html。这意味着，如果你有一个文章模型（假设表名为 article）中 ID 为 10 的文章，你可以创建一个 article/10.html 文件来专门展示它。
  • 文档列表默认自定义模板：可以命名为 {模型table}/list-{分类id}.html。例如，article/list-5.html 可以作为文章模型中分类 ID 为 5 的列表页模板。
  • 单页面默认自定义模板：可以命名为 page/{单页面id}.html。比如，ID 为 1 的单页面，系统会尝试寻找 page/1.html。

这些默认约定极大地提升了模板的自动化应用能力。此外，AnQiCMS 也提供了高度的灵活性，支持更个性化的自定义命名。例如，如果你想为“关于我们”这个单页面设计一个独特的模板，你可以将模板文件命名为 page/about.html，然后在后台创建单页面时，将其“文档模板”字段设置为 about.html。系统会优先按照后台设置的自定义模板路径来加载。

为什么这些约定很重要？

遵循这些命名和结构约定，不仅能让你的模板项目保持整洁有序，更有多方面的好处：

  1. 提高开发效率：标准化命名减少了猜测，让开发者能快速定位和修改文件。
  2. 简化维护和协作：无论是团队协作还是后期维护，清晰的结构和统一的命名都能降低沟通成本。
  3. 确保系统兼容性：尤其是默认的命名约定，能够让 AnQiCMS 自动识别并正确加载模板，避免因命名不规范导致的问题。
  4. 利于版本升级：系统升级时，如果模板结构符合约定，可以有效减少因结构变化带来的兼容性问题。

理解并熟练运用 AnQiCMS 的模板文件命名和目录结构约定，是每一位 AnQiCMS 用户发挥其强大定制能力、构建高质量网站的基础。

常见问题 (FAQ)

Q1: 如果我的模板文件没有按照这些约定命名，AnQiCMS 会完全无法识别吗？

A1: 不完全是。对于一些核心页面，例如主页、模型详情页和列表页，AnQiCMS 会首先尝试查找默认命名模式的模板。如果找不到，它会继续寻找后台设置中指定的自定义模板文件。如果两者都未找到，系统通常会退回使用默认的内置逻辑或报错。但强烈建议遵循约定，这能确保模板被正确识别和应用，并提高开发和维护效率。

Q2: 为什么有些默认模板的命名中包含 {模型table} 或 {分类id} 这样的占位符？它们会如何被替换？

A2: 这些占位符是为了实现模板的动态匹配和复用而设计的。{模型table} 会被替换为当前内容模型的数据库表名（例如 article、product），而 {分类id} 或 {文档id} 则会被替换为对应的分类 ID 或文档 ID。这样做的好处是，你可以为特定模型下的特定分类或特定文档创建独立的模板，而无需为每个文章或分类在后台手动指定模板路径，系统能自动识别