如何为 AnQiCMS 的特定文档、分类或单页面使用自定义模板？

作为一名资深的安企CMS(AnQiCMS)网站运营人员，我深知内容在吸引和留住用户方面的重要性，而灵活的模板系统是实现个性化内容展示的关键。AnQiCMS 提供了强大的自定义模板功能，让运营人员可以根据不同内容的需求，打造独一无二的页面布局和风格。

AnQiCMS 模板工作原理概述

AnQiCMS 的模板系统基于 Go 语言，采用了类似 Django 的模板引擎语法，文件以 .html 为后缀，并统一存放在网站根目录下的 /template 文件夹中。每一套模板都拥有独立的目录，例如 default 模板会存放在 /template/default。模板内部通过双花括号 {{变量}} 调用变量，通过单花括号和百分号 {% 标签 %} 定义逻辑标签（如条件判断、循环控制）。

AnQiCMS 的设计理念是灵活且易于定制，其模板机制允许用户为网站的特定文档、分类页面或单页面应用专属的布局，从而实现高度个性化的内容呈现。

自定义模板的定义与应用

在 AnQiCMS 中，为特定内容应用自定义模板主要有两种方式：自动命名约定和手动指定。

文档（Archive）的自定义模板

默认情况下，AnQiCMS 会为文章、产品等模型下的文档详情页使用 {模型table}/detail.html 作为通用模板。例如，文章模型默认使用 article/detail.html，产品模型默认使用 product/detail.html。

然而，当您希望某一篇文章或某一个产品拥有完全不同的展示样式时，可以应用自定义模板：

  1. 自动命名约定：AnQiCMS 支持根据文档 ID 自动匹配模板。您可以在当前使用的模板目录下，创建一个名为 {模型table}/{文档ID}.html 的文件。例如，如果您有一个文章模型的文档 ID 为 10，您可以创建一个 article/10.html 文件。当用户访问 ID 为 10 的文章时，系统会优先加载这个自定义模板。
  2. 后台手动指定：在 AnQiCMS 后台编辑或发布文档时，找到“其他参数”折叠框，其中有一个名为“文档模板”的字段。您可以在此处直接填写自定义模板的文件名，例如 download.html。系统会尝试在当前模板目录下查找并使用您指定的文件作为该文档的显示模板。请务必确保您填写的模板文件实际存在于您当前启用的模板主题中。

通过这两种方式，您可以为例如“招聘信息”文章、“联系我们”产品等特殊内容，提供量身定制的页面体验。

分类（Category）的自定义模板

AnQiCMS 同样允许为特定分类页面设置自定义模板。默认情况下，分类列表页会使用 {分类模型}/list.html 作为通用模板。例如，文章模型的分类列表页使用 article/list.html，产品模型使用 product/list.html。

如果您需要某个分类页面（例如“新闻资讯”分类列表页）具有独特的布局，可以按以下方式操作：

  1. 自动命名约定：您可以根据分类 ID 创建自定义模板文件。在当前模板目录下，创建一个名为 {模型table}/list-{分类ID}.html 的文件。例如，如果文章模型下有一个分类 ID 为 5 的“公司新闻”，您可以创建 article/list-5.html 文件。当用户访问这个分类时，AnQiCMS 会优先加载此文件。
  2. 后台手动指定：在 AnQiCMS 后台编辑分类时，找到“其他参数”折叠框，其中有一个“分类模板”字段。您可以在此填写自定义模板的文件名，例如 news_category.html。系统将使用该文件作为此分类的列表显示模板。 此外，分类设置中还有一个“文档模板”字段，它用于指定该分类下所有文档详情页的默认模板。如果某个分类下的所有文章都需要相同的特殊样式，可以在这里设置，例如 news_detail.html。 还有一个名为“是否应用到子分类”的选项。默认情况下，自定义的分类模板不会继承给子分类。如果勾选此选项，该分类下的所有子分类将统一使用父分类设定的自定义模板。

通过这些设置，您可以为不同类型的分类（如“成功案例”、“合作伙伴”）设计独特的分类页面，以更好地展示内容。

单页面（Page）的自定义模板

单页面通常用于“关于我们”、“联系方式”、“法律声明”等独立页面。默认情况下，AnQiCMS 单页面会使用 page/detail.html 作为通用模板。

要为某个单页面创建自定义模板：

  1. 自动命名约定：您可以根据单页面 ID 或其别名来创建模板。
    • 按 ID：在当前模板目录下，创建一个名为 page/{单页面ID}.html 的文件。例如，单页面 ID 为 20，可以创建 page/20.html。
    • 按别名：在 AnQiCMS 后台编辑单页面时，可以为其设置一个“自定义 URL”别名（例如 about）。然后，您可以创建 page/about.html 文件。当用户访问这个别名的单页面时，系统会优先加载此模板。
  2. 后台手动指定：在 AnQiCMS 后台编辑单页面时，找到“单页面模板”字段。您可以在此填写自定义模板的文件名，例如 contact_us.html。系统会尝试在当前模板目录下查找并使用您指定的文件作为该单页面的显示模板。

这种方式非常适合为网站的关键单页面（如企业介绍、隐私政策）提供定制化的展示，确保品牌形象和信息传递的一致性。

模板文件存放位置和命名约定

所有自定义模板文件都应放置在当前启用主题的 /template/{主题名称}/ 目录下。

  • 文件类型：所有模板文件必须使用 .html 作为文件扩展名。
  • 编码：模板文件应统一采用 UTF-8 编码，以避免乱码问题。
  • 目录结构：AnQiCMS 支持两种模板组织模式：
    • 文件夹组织模式：如 article/detail.html, page/detail.html 等，这是一种推荐的结构，有助于保持模板文件的清晰组织。
    • 扁平化文件组织模式：如 article_detail.html, page.html 等，适合文件较少或偏好简化目录结构的用户。 无论采用哪种模式，关键是保持命名的一致性，并确保系统能够正确识别和加载。

操作步骤总结

  1. 选择或创建模板文件：根据需求，创建一个新的 .html 文件，或复制现有模板文件进行修改。
  2. 放置模板文件：将新模板文件上传至 /template/{您的主题目录}/ 下的相应位置（例如 article/ 文件夹用于文章，page/ 文件夹用于单页面）。
  3. 在后台指定模板：
    • 文档：编辑特定文档，在“其他参数”中填写“文档模板”的文件名。
    • 分类：编辑特定分类，在“其他参数”中填写“分类模板”的文件名。
    • 单页面：编辑特定单页面，在“单页面模板”中填写模板的文件名。
  4. 验证：访问对应的前台页面，检查自定义模板是否正确应用。

注意事项

  • 模板文件必须存在：无论采用哪种方式指定自定义模板，都必须确保对应的 .html 文件真实存在于您当前使用的主题目录下。如果文件不存在，页面将无法正常打开。
  • 优先级：自动命名约定的模板（如 article/10.html）通常具有更高的优先级，会优先于后台手动指定的模板。而手动指定的模板优先级高于默认模板。
  • UTF-8 编码：确保所有模板文件都以 UTF-8 编码保存，以防止中文内容显示乱码。

通过以上详尽的步骤和说明，您可以灵活地为 AnQiCMS 网站上的任何特定文档、分类或单页面应用自定义模板，从而实现丰富多彩且功能强大的内容展示。

常见问题解答 (FAQ)

  1. 如果我指定的自定义模板文件不存在，会发生什么？ 如果 AnQiCMS 尝试加载一个不存在的自定义模板文件，页面将无法正常显示，通常会导致 404 错误或系统报错页面，提示找不到指定的模板文件。因此，在后台指定或按约定命名模板文件后，务必确认该文件已上传并路径正确。

  2. 自定义模板的优先级是怎样的？ AnQiCMS 模板加载的优先级遵循从特殊到一般的原则：

    • 最高优先级：自动命名约定的模板文件（例如 article/10.html 或 page/about.html）。
    • 次高优先级：后台管理界面手动指定的模板文件（例如文档模板字段中填写的 custom_article.html）。
    • 最低优先级：对应内容类型的默认通用模板（例如 article/detail.html 或 page/detail.html）。 这意味着，如果存在 article/10.html，并且后台又指定了 custom_article.html，系统会优先使用 article/10.html。

  3. 我可以在自定义模板中引用其他的模板文件吗？ 可以。AnQiCMS 的模板引擎支持 include 和 extends 标签，您可以在自定义模板