在 AnQiCMS 的模板开发中，为了提高代码复用性、降低维护成本，我们经常会用到一些强大的模板功能，其中“宏函数（macro）”和“Include 标签”便是两位得力助手。它们各自拥有独特的优势和适用场景，理解并恰当运用，能让模板开发事半功倍，构建出高效、易于维护的网站。

宏函数（Macro）：封装可复用的动态逻辑

宏函数在模板开发中，就像编程语言里的函数一样。我们可以定义一段可重复使用的代码片段，并为其指定参数。当需要这段代码时，只需“调用”它，并传入相应的参数，它就会根据传入的数据渲染出不同的内容。宏函数拥有独立的上下文，这意味着它只关注传入的参数，不会意外地修改或依赖外部变量，使得代码更加健壮和可预测。

在 AnQiCMS 中，宏函数的应用场景非常广泛，特别适用于那些结构相似但内容动态变化的 UI 组件。

适用场景：

  • 动态列表项的渲染： 想象一下网站中常见的文章列表、产品列表、用户评论列表等。它们每一个列表项的 HTML 结构可能都大同小异（例如都包含标题、描述、链接、图片），但每个项所展示的具体数据却截然不同。此时，我们可以定义一个宏函数，比如 article_item(article)，接收一个 article 对象作为参数。在循环遍历文章数据时，只需调用这个宏函数，传入当前文章的数据，即可生成对应的列表项 HTML。这在处理像 archiveList、categoryList、pageList 这样的标签返回的数据时非常高效。例如文档中 tag-tags.md 就展示了如何定义和使用 archive_detail(archive) 宏来渲染文章列表项。
  • 复杂 UI 组件的封装： 当一个较小的 UI 单元，如带有用户头像和昵称的评论区头部、一个统计数据展示模块，其渲染逻辑包含复杂的条件判断或数据处理时，将其封装为宏函数能够有效减少代码冗余，提高可读性。
  • 可配置的通用模块： 如果网站上有需要根据不同参数（如显示数量、是否显示缩略图、排序方式等）来调整渲染方式的通用模块，例如“最新文章推荐”、“热门标签云”等。通过宏函数可以接收这些参数，实现灵活的配置和复用，而无需为每种配置编写一套新的 HTML。
  • 抽离到独立文件进行管理： AnQiCMS 允许将宏函数的定义存储在独立的模板文件（例如 archive.helper）中。当主模板需要使用这些宏时，可以通过 import 标签引入。这种方式有助于保持主模板的整洁，并让宏函数定义文件专注于封装可重用逻辑，提升模板结构的可维护性。

Include 标签：引入静态或半静态的页面片段

Include 标签的作用相对直接，它用于将另一个模板文件的内容直接插入到当前位置。你可以将其理解为一个简单的文本替换操作：模板引擎会将指定文件的内容原封不动地嵌入到 include 标签所在的位置。被引入的文件可以访问当前模板的所有变量，也可以通过 with 关键字接收指定的变量，甚至可以使用 only 关键字限制其只访问指定变量。

在 AnQiCMS 模板结构中，include 标签是构建页面骨架、实现模块化布局的基础。

适用场景：

  • 网站公共结构： 这是 include 标签最经典的用法。网站的头部 (header)、底部 (footer)、侧边栏 (aside)、全局导航菜单等，这些内容在整个网站中是固定不变或变化很小的。AnQiCMS 模板制作的基本约定中就提到 bash.html（页头、页脚等公共部分）和 partial/ 目录（代码片段），正是为 include 而设计。将这些公共部分拆分为独立文件，然后通过 include 标签在各个页面中引入，可以大幅提高开发效率，并确保网站整体风格的一致性。
  • 常用的静态或半静态代码片段： 例如，一个统一的面包屑导航 (tag-breadcrumb.md 标签可以生成数据，但渲染 HTML 结构可以用 include 封装)、网站的版权声明、统一的 CSS 或 JavaScript 引入块、固定的广告位代码，或者从后台设置中获取的联系方式 (tag-contact.md 标签获取数据) 和系统信息 (tag-system.md 标签获取数据) 的渲染模块。这些内容通常变化不大，通过 include 引入可以方便管理和复用。
  • 模块化页面布局： 对于复杂的页面，可以将不同区域（如产品详情页的“产品参数区”、“客户评价区”）拆分成独立的模板文件。然后，在主模板中使用 include 标签将这些模块按需组合起来。这样，每个模块可以独立开发和维护，提高了页面的模块化程度和可读性。

如何选择：宏函数 vs Include 标签

在 AnQiCMS 模板开发中，理解宏函数和 Include 标签的侧重点是关键：

  • 选择 Include 当： 你需要插入一个相对固定的 HTML 结构，或者一个完整的、独立的页面片段。其内容主要来源于文件本身，而非通过参数动态生成。它更偏向于结构化和文件组合。例如，页眉、页脚通常变化不大，直接 include 即可。
  • 选择 Macro 当： 你需要封装一段可重复使用的渲染逻辑，这段逻辑需要接收不同的数据或配置参数来生成不同的 HTML 输出。它更偏向于函数化和动态生成。例如，文章列表中的每个文章项，虽然结构固定，但内容随文章变化，用 macro 传入文章数据来渲染就非常合适。

在实际开发中，两者并非互斥，而是常常结合使用。你可以 include 一个包含多个宏定义的文件，然后在主模板中调用这些宏。或者，一个 include 的文件内部，也可能调用其他 macro 来渲染其内部的动态部分。这种组合使用