在安企CMS中，高效地管理网站内容和前端展示是日常运营的关键。当我们面对一些重复出现的页面元素，比如文章列表项、产品卡片或者带有特定样式的按钮时，如果每次都重新编写代码，不仅耗时耗力，还容易出错，并且未来的修改和维护也会变得异常复杂。幸运的是，安企CMS提供了强大的模板引擎，其中macro宏函数就是解决这一痛点的利器，它能帮助我们定义可复用的内容显示片段，从而大幅提高开发效率和模板的可维护性。
macro宏函数，您可以把它想象成是模板中的“小函数”或者“内容组件”。它允许您封装一段带有特定逻辑和样式的HTML代码，并给这段代码定义一些参数。当您需要使用这段代码时，只需像调用函数一样调用这个宏，并传入相应的参数，就能快速生成所需的内容。这样一来，您就避免了重复编写相同的模板代码，让模板结构更清晰，也更容易管理。
定义一个宏函数
要在安企CMS模板中定义一个宏函数，您会用到{% macro %}和{% endmacro %}这对标签。宏函数需要一个名称，以及可以接收的参数列表，这些参数在宏内部就像普通变量一样使用。
我们以一个常见的场景为例：在网站的各个地方，您可能都需要显示一个结构相似的文章摘要卡片，包含文章标题、链接、简介和缩略图。我们可以这样定义一个宏：
{# 定义在 /template/您的模板目录/partial/_article_card.html 文件中 #}
{% macro article_card(article) %}
<div class="article-card">
<a href="{{ article.Link }}" class="article-link">
{% if article.Thumb %}
<img src="{{ article.Thumb }}" alt="{{ article.Title }}" class="article-thumb">
{% endif %}
<h3 class="article-title">{{ article.Title }}</h3>
<p class="article-description">{{ article.Description|truncatechars:100 }}</p>
<span class="article-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
</a>
</div>
{% endmacro %}
在这个例子中，我们定义了一个名为article_card的宏，它接收一个名为article的参数。在宏的内部，我们使用article的属性（如Link、Title、Thumb、Description、CreatedTime）来构建HTML结构。请注意，这里我们使用了truncatechars过滤器来截断文章简介，并用stampToDate函数格式化了发布时间，这些都是安企CMS模板引擎提供的强大功能。
在模板中引入并使用宏
一旦您定义了宏，就可以在需要使用它的任何模板文件中引入并调用。安企CMS鼓励将这类可复用的代码片段存放在partial/目录下，这样结构更清晰。
假设您将上面定义的article_card宏保存在了/template/您的模板目录/partial/_article_card.html文件中。现在，在您的首页模板（例如index/index.html）或其他列表页模板中，您可以通过import标签来引入它：
{# 在 /template/您的模板目录/index/index.html 文件中 #}
{# 引入宏文件，并给引入的宏函数指定一个别名 card #}
{% import "partial/_article_card.html" as card %}
<section class="latest-articles">
<h2>最新文章</h2>
<div class="article-list-grid">
{% archiveList articles with type="list" moduleId="1" limit="6" order="id desc" %}
{% for item in articles %}
{# 调用宏，并传入当前文章数据 #}
{{ card.article_card(item) }}
{% endfor %}
{% empty %}
<p>暂时没有文章发布。</p>
{% endarchiveList %}
</div>
</section>
<section class="recommended-articles">
<h2>推荐文章</h2>
<div class="article-list-flex">
{% archiveList recommendedArticles with type="list" moduleId="1" limit="4" flag="c" order="views desc" %}
{% for item in recommendedArticles %}
{# 在另一个区域再次调用宏，显示推荐文章 #}
{{ card.article_card(item) }}
{% endfor %}
{% empty %}
<p>暂时没有推荐文章。</p>
{% endarchiveList %}
</div>
</section>
在这个例子中：
- 我们使用
{% import "partial/_article_card.html" as card %}来引入了宏文件，并通过as card给宏组件赋予了一个更简洁的命名空间。 - 接着，在不同的文章列表（最新文章和推荐文章）的循环中，我们都调用了
{{ card.article_card(item) }}。这里的item就是archiveList标签循环出来的每一篇文章数据，它被作为参数传递给了article_card宏。
您可以想象一下，如果没有macro，您可能需要在每个for循环中复制粘贴一模一样的HTML结构和数据渲染逻辑。一旦需要修改文章卡片的样式或显示内容（比如增加一个阅读量字段），您就需要在所有用到它的地方逐一修改，这无疑是费时且容易出错的。而有了macro，您只需要修改_article_card.html这一个文件，所有引用它的地方都会同步更新，大大提高了效率和一致性。
macro的优势与应用场景
macro宏函数的强大之处体现在以下几个方面：
- 减少代码重复： 封装重复出现的UI组件，让您的模板代码更精简。
- 提高维护效率： 修改一处宏定义，所有使用它的地方都会自动更新，避免了繁琐的全局查找替换。
- 增强代码可读性： 宏函数将复杂的HTML结构和逻辑抽象成一个简单的调用，使模板代码更易于理解。
- 促进团队协作： 不同的开发者可以专注于不同宏的开发，然后轻松地在主模板中集成使用。
除了文章卡片，macro还可以应用于很多地方，比如：
- 产品列表项： 在电商网站中，产品缩略图、名称、价格、购买按钮等组成的产品卡片。
- 评论显示： 统一的评论用户头像、用户名、评论内容和时间戳的显示格式。
- 面包屑导航项： 如果您的面包屑导航有多种样式或复杂的链接逻辑。
- 按钮组： 带有特定图标、文本和链接的按钮组合。
- 表单输入字段： 带有标签、占位符和验证提示的标准化输入框。
通过灵活运用macro宏函数，您将能够更优雅、更高效地构建和维护您的安企CMS网站模板。
常见问题 (FAQ)
1. macro宏函数和include标签有什么区别？
include标签是直接将一个模板文件的全部内容插入到当前位置，它会继承当前模板的所有上下文变量。而macro宏函数则更像一个独立的小程序，它只接收作为参数传入的变量，并且有自己独立的作用域，不能直接访问宏定义外部的变量。简单来说，include是直接复制代码片段，macro是定义一个可调用、可传参的函数式组件。
2. macro宏函数可以访问宏外部的变量吗？
不可以。macro宏函数具有限定的作用域，它只能访问通过参数传入的变量。这意味着，如果宏内部需要使用任何数据，您都必须显式地将其作为参数传递进去。这是为了保证宏的独立性和可复用性，避免其行为受到外部环境的意外影响。
3. 宏文件应该放在模板目录的哪个位置？
为了保持模板结构的清晰和规范，强烈建议将宏定义文件存放在您的模板目录下的partial/子目录中。例如，如果您的模板目录是default，那么宏文件可以放在/template/default/partial/_macros.html，或者根据功能进一步细分，如/template/default/partial/_article_snippets.html等。这样做有助于管理和查找可复用的代码片段。