在 AnQiCMS 中，内容能否正确、优雅地呈现在用户眼前，很大程度上取决于模板文件的组织方式和命名规范。理解这些基本约定，能够帮助您更高效地设计和管理网站界面，确保内容的精准呈现。

模板文件的基石：/template 目录和 .html 后缀

AnQiCMS 对模板文件的放置位置有着明确的规定：所有的模板文件都必须存放在网站根目录下的 /template 文件夹中。这个目录是 AnQiCMS 查找和加载模板的唯一入口。同时，模板文件统一使用 .html 作为后缀，这不仅是系统识别模板的标志，也符合前端开发的普遍习惯。

当您创建或编辑模板文件时，还需要特别注意文件编码。AnQiCMS 要求模板文件统一采用 UTF-8 编码。如果使用了其他编码格式，页面在显示时很可能会出现乱码，影响用户体验。对于习惯在 Windows 环境下进行编辑的用户，务必在保存时选择 UTF-8 格式。

此外，模板所需的样式表（CSS）、JavaScript 脚本和图片等静态资源，则不应直接放置在 /template 目录下。AnQiCMS 提供了专门用于存放这些静态资源的 /public/static/ 目录。将静态资源与模板文件分离，有助于提高网站的加载效率和维护便利性。

灵活的组织方式：文件夹模式与扁平化模式

AnQiCMS 提供了两种主要的模板组织模式，以适应不同规模和复杂度的网站需求：

  1. 文件夹组织模式： 这种模式通过创建子文件夹来分类存放模板，结构清晰，易于管理大型项目。例如，首页模板可能位于 index/index.html，文章详情页模板位于 article/detail.html，产品列表页模板则位于 product/list.html。对于一些页面通用的代码片段，比如网站的页头（header）、页脚（footer）或侧边栏（sidebar），通常会存放在 partial/ 目录中，并通过 include 标签在需要的地方引用，实现代码复用。这种分层结构让开发者能够快速定位和修改特定功能的模板，极大地提升了维护效率。

  2. 扁平化文件组织模式： 对于结构相对简单、页面数量不多的网站，扁平化模式可能更为便捷。在这种模式下，大部分模板文件直接存放在模板的根目录，通过约定好的命名来区分不同类型的页面。例如，首页模板可能是 index.html，文章详情页模板是 article_detail.html，产品列表页模板是 product_list.html。这种模式减少了目录层级，让文件一目了然，适合快速开发和轻量级维护。

无论选择哪种模式，关键在于保持一致性，并遵循 AnQiCMS 的命名约定。因为系统会根据这些约定来自动匹配内容与模板，确保内容的正确显示。

针对移动端的特别考量：mobile/ 目录

随着移动互联网的普及，响应式设计或独立的移动端页面变得越来越重要。AnQiCMS 考虑到了这一点，提供了对移动端模板的良好支持。

如果您的网站选择使用“代码适配”或“电脑+手机独立站点”的模板类型，AnQiCMS 将会在您当前的模板目录下寻找一个名为 mobile/ 的子目录。这个 mobile/ 目录的内部结构和文件命名规则与主模板目录（PC端）是完全一致的。这意味着，如果您有一个 article/detail.html 用于 PC 端文章详情，那么对应的移动端文章详情模板就应该放在 mobile/article/detail.html。这样，AnQiCMS 就能根据访问设备的类型，自动加载并显示相应的模板，为不同设备的用户提供**的浏览体验。

模板的“身份证”：config.json

每一套 AnQiCMS 模板都需要一个“身份证”——即在模板目录下的 config.json 文件。这个文件包含了模板的基本信息，让 AnQiCMS 能够识别并正确管理这套模板。

config.json 中包含了一些重要的字段：

  • name：模板的显示名称，方便您在后台选择和识别模板。
  • package：模板文件夹的名称，通常是英文字母和数字的组合，作为模板的唯一标识。
  • version：模板的版本号，便于追踪和更新。
  • template_type：这是一个关键字段，定义了模板的类型。例如，0 代表自适应模板（一套模板适配所有设备），1 代表代码适配（需要独立的 mobile 目录），2 代表电脑+手机独立站点。
  • status：表示模板的启用状态，0 为未启用，1 为使用中。在所有模板中，只能有一个 status 值为 1 的模板处于启用状态。

通过 config.json，AnQiCMS 不仅能了解模板的基本属性，还能据此进行模板的切换和功能适配。

智能匹配：预设的模板名称

AnQiCMS 的另一个便捷之处在于它对某些特定页面的智能识别。如果您按照系统预设的命名规则创建模板文件，即使不在后台手动设置，AnQiCMS 也能自动应用这些模板。这大大简化了模板配置流程。

一些常见的预设模板名称包括：

  • 文档详情页： {模型table}/{文档id}.html 或 {模型table}/detail.html。例如，article/123.html 会匹配 ID 为 123 的文章，而 article/detail.html 则会作为所有文章的默认详情页模板。
  • 文档列表页： {模型table}/list-{分类id}.html 或 {模型table}/list.html。例如，product/list-45.html 会匹配 ID 为 45 的产品分类列表，而 product/list.html 则是所有产品分类的默认列表模板。
  • 单页面详情页： page/{单页面id}.html 或 page/detail.html。例如，page/about-us.html 可以作为“关于我们”页面的专属模板。

这种智能匹配机制提供了一定的灵活性。您可以为特定的文档、分类或单页面创建定制化的模板文件，而无需更改其他通用页面的模板。如果您有一个名为 about.html 的单页面模板，只需在后台的单页面管理中指定该页面的模板为 page/about.html，系统就会自动加载它。

总而言之，AnQiCMS 的模板文件命名和目录结构是其内容显示机制的核心。通过将所有模板文件统一存放于 /template 目录，并使用 .html 扩展名和 UTF-8 编码，可以确保系统正确识别和解析。同时，根据网站规模选择文件夹组织或扁平化组织模式，配合 mobile/ 目录处理移动端显示，以及 config.json 文件管理模板元信息，能够实现高效的模板开发和维护。而系统对预设模板名称的智能识别功能，则进一步提升了内容与模板匹配的便捷性与灵活性。掌握这些约定，您的 AnQiCMS 网站将能以最理想的方式呈现给访问者。

常见问题 (FAQ)

1. 如果我的模板文件不在 /template 目录中，或者文件后缀不是 .html，AnQiCMS 还能正常显示内容吗？ 不可以。AnQiCMS 严格要求模板文件必须存放在 /template 目录下，并以 .html 作为文件后缀，否则系统将无法识别和加载这些模板，导致内容无法正常显示，甚至可能出现页面错误。

2. AnQiCMS 是如何决定一个特定页面（比如某篇文章或产品详情页）应该使用哪个模板的？ AnQiCMS 会根据一套优先级规则来决定。首先，它会检查后台是否为该文章、分类或单页面指定了自定义模板。如果没有，它会尝试寻找与内容模型、分类ID或单页面ID相匹配的预设模板文件（例如 article/detail.html 或 product/list-123.html）。最后，如果上述规则都没有匹配到，系统会回退到默认的通用模板。

3. 我能否在一个模板主题中同时使用文件夹组织模式和扁平化文件组织模式？ 从技术上讲，您可以在一个模板主题下混合使用这两种模式，因为 AnQiCMS 会根据约定的路径去寻找文件。但是，为了保持模板结构的一致性、可维护性，以及避免潜在的文件命名冲突或混淆，强烈