AnQiCMS 提供了强大而灵活的模板系统，让网站内容的展示高度可定制。其模板标签语法借鉴了 Django 模板引擎，并融合了 Blade 模板的易用性，使得即使是不熟悉 Go 语言的用户也能轻松上手。然而，要充分发挥模板标签的潜力并避免常见错误，理解其正确的使用方式和潜在陷阱至关重要。

AnQiCMS 模板标签基础：理解核心语法和约定

AnQiCMS 的模板文件通常以 .html 为后缀，存储在 /template 目录中。模板中处理数据输出和逻辑控制的核心语法是双花括号 {{变量}} 和单花括号加百分号 {% 标签 %}。

  • 数据输出 ({{变量}})：用于直接显示数据，例如 {{archive.Title}} 会输出文章的标题。变量名通常遵循驼峰命名法（首字母大写），例如 Id、Title、CreatedTime 等。
  • 逻辑控制 ({% 标签 %})：用于实现条件判断、循环遍历、引入文件等功能。这类标签需要成对出现，有开始标签和结束标签，例如 {% if 条件 %}...{% endif %} 或 {% for item in 列表 %}...{% endfor %}。

在实际使用中，模板文件还会配合 /public/static/ 目录存放的 CSS、JavaScript、图片等静态资源。为了确保模板能够被正确解析，所有模板文件都应使用 UTF-8 编码保存。

AnQiCMS 还支持一些默认的模板文件命名约定，例如文档列表可以命名为 {模型table}/list-{分类id}.html，单页面可以命名为 page/{单页面id}.html。了解这些约定能帮助我们更好地组织模板文件，并实现特定页面内容的个性化展示。

避免常见错误的关键策略

要正确使用 AnQiCMS 模板标签，避免常见问题，以下几个方面是我们需要特别注意的：

  1. 严格的大小写敏感性：AnQiCMS 的模板标签和变量名对大小写非常敏感。例如，{{archive.id}} 和 {{archive.Id}} 是两个不同的变量。标签名称如 archiveList 和 archivelist 也不能混用。一个小小的拼写错误就可能导致标签无法识别或数据无法正常显示。
  2. 标签的正确闭合：所有逻辑控制标签（如 {% if %}、{% for %}、{% archiveList %} 等）都必须有对应的结束标签（{% endif %}、{% endfor %}、{% endarchiveList %}）。忘记闭合标签是初学者常犯的错误，会导致模板解析错误甚至页面崩溃。
  3. 参数的准确传递：许多标签需要通过参数来指定获取哪些数据或如何处理。例如，{% archiveDetail with name="Title" id="1" %} 中，name 参数指定要获取的字段，id 参数指定文章的 ID。不同标签支持的参数不同，务必查阅相关文档，确保参数名称和取值范围的正确性。特别注意 moduleId、categoryId、type、limit 等常用参数的用法。
  4. 新旧标签的更迭：AnQiCMS 在 v2.1.1 版本中重构了模板标签，移除了原有的 article 和 product 标签，统一新增了 archive 标签。这意味着，如果您的网站是从旧版本升级而来，或者参考了旧版教程，仍然使用 articleList 或 productDetail 等标签，将会导致错误。务必改用新的 archiveList、archiveDetail 等统一的 archive 系列标签。
  5. 数据类型与过滤器的匹配：在输出数据时，有时需要对数据进行格式化或处理。
    • 时间戳转换：CreatedTime 和 UpdatedTime 等字段通常返回 Unix 时间戳，需要使用 stampToDate 标签将其格式化为可读日期，例如 {{stampToDate(item.CreatedTime, "2006-01-02 15:04")}}。
    • HTML 内容的安全输出：文章详情 (archive.Content)、分类内容 (category.Content) 等字段可能包含 HTML 标签。直接输出会被默认转义以防止 XSS 攻击，导致 HTML 代码显示为纯文本。若要正确解析 HTML，需要使用 |safe 过滤器，例如 {{archive.Content|safe}}。
    • Markdown 内容渲染：如果内容是用 Markdown 编写的，开启 Markdown 编辑器后，内容会自动转换。若需手动控制转换，可添加 render 参数，或使用 |render 过滤器，例如 {{archive.Content|render|safe}}。
    • 内容截取：对于过长的文本，可以使用 |truncatechars:100（按字符截取）或 |truncatewords:50（按单词截取）等过滤器进行截断并添加省略号。
  6. 上下文依赖的理解：一些标签（例如 archiveDetail、categoryDetail）在没有明确指定 id 或 token 参数时，会尝试自动获取当前页面的上下文数据。在文档详情页使用 archiveDetail 会自动获取当前文档数据，但在首页使用时，则需要明确指定 id 参数来获取特定文档的数据。
  7. 正确引用静态资源和模板路径：在模板中引用静态资源（图片、CSS、JS）时，应使用 {% system with name="TemplateUrl" %} 标签来获取当前模板的静态资源根路径，例如 <link href="{% system with name="TemplateUrl" %}/css/style.css" rel="stylesheet">。在 include 其他模板片段时，路径也要相对正确，例如 {% include "partial/header.html" %}。

实战指南：常用标签的正确打开方式

AnQiCMS 提供了丰富的标签，以下列举一些常用标签的正确使用方式，并指出其需要注意的地方：

  • 全局信息获取 (system, contact, tdk)：

    • {% system with name="SiteName" %}：获取网站名称。这类标签通常不需要 end 标签，直接输出结果。
    • {% contact with name="Cellphone" %}：获取联系电话。可以自定义名称方便调用，如 {% contact myPhone with name="Cellphone" %}{{myPhone}}。
    • {% tdk with name="Title" siteName=true %}：获取页面标题，并可选择是否附加网站名称。 siteName 参数只对 Title 生效。

  • 内容列表与详情 (archiveList, archiveDetail, categoryList, categoryDetail, pageList, pageDetail)：

    • 文章/产品列表：{% archiveList archives with moduleId="1" type="page" limit="10" %}
      • moduleId：指定内容模型 ID（如 1 为文章，2 为产品）。这是非常重要的筛选条件。
      • type：可以是 list (固定数量列表) 或 page (分页列表)。
      • limit：限制显示数量。对于 type="page"，需配合 {% pagination %} 标签使用。
      • categoryId：指定分类 ID。多个 ID 用逗号隔开。
      • 在循环体内，使用 for 标签遍历 archives，通过 {{item.Title}}、{{item.Link}} 等获取字段。
    • 文章/产品详情