如何创建可复用的模板代码片段（宏）？
在安企CMS的日常内容运营中，我们常常会遇到一些需要反复使用的界面元素或代码结构。例如，一个标准化的文章列表项、一个统一风格的产品展示卡片，或者一个带有特定排版信息的页脚联系方式。如果每次都手动编写这些代码，不仅效率低下，还容易出现格式不一致的问题。这时，安企CMS提供的“宏”（Macro）功能就显得尤为重要，它能帮助我们轻松创建可复用的模板代码片段，大幅提升模板开发的效率和代码质量。
什么是模板宏（Macro）？
宏，在安企CMS的模板引擎（基于Django模板语法）中，可以被理解为模板中的“函数”或“小组件”。它们允许我们封装一段带有特定逻辑和结构的HTML或代码片段，并为其定义一些可传入的参数。当需要使用这段代码时，我们只需像调用函数一样调用宏，并传入相应的参数，宏就会根据这些参数生成预定义的内容。
为什么使用模板宏？
使用宏能带来诸多好处：
- 减少重复代码（DRY原则）：避免在多个模板文件中复制粘贴相同的代码块，使模板更简洁。
- 提升代码可维护性：一旦某个宏的显示逻辑或结构需要调整，只需修改宏的定义文件，所有引用该宏的地方都会自动更新，无需逐一修改。
- 保持页面风格一致性：通过统一的宏来渲染特定的UI组件，可以确保网站各处呈现相同的视觉和交互风格。
- 提高开发效率：一旦宏定义完成，后续开发可以直接调用，大大缩短了开发时间。
如何创建和使用宏？
安企CMS的宏功能强大且灵活，既可以在单个模板文件中定义和使用，也可以拆分到独立的宏文件中进行集中管理和引入。
1. 在当前模板文件中定义和使用宏
最简单的宏用法是直接在当前模板文件的顶部或任何需要的位置定义它。宏的定义使用{% macro %}和{% endmacro %}标签包裹，并可以声明接受的参数。
宏定义示例： 假设我们需要一个统一的文章列表卡片显示样式，包含文章标题和链接。
{% macro article_card(article) %}
<div class="article-item">
<h3 class="article-title"><a href="{{ article.Link }}">{{ article.Title }}</a></h3>
{% if article.Description %}
<p class="article-description">{{ article.Description }}</p>
{% endif %}
<span class="article-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
</div>
{% endmacro %}
在这个例子中，article_card是宏的名称，article是它接受的参数，我们期望传入一个包含文章信息的对象。
宏调用示例： 在同一个模板文件中，当我们获取到文章列表数据后，就可以像这样调用宏：
{% archiveList articles with type="list" limit="5" %}
{% for item in articles %}
{{ article_card(item) }} {# 调用上面定义的宏，传入每篇文章的数据 #}
{% endfor %}
{% endarchiveList %}
这样，每篇文章都会被渲染成统一的article_card样式。
2. 将宏独立存放到专用文件中
当宏的数量增多，或者需要在多个模板文件中复用同一个宏时，建议将宏定义单独存放到一个文件。根据安企CMS的模板约定，这类代码片段通常放置在模板根目录下的partial/目录中。
步骤1：创建宏文件
在你的模板目录（例如template/default/）下，创建一个partial/目录，并在其中创建一个文件，比如_macros.html（下划线前缀是一种常见约定，表示这是一个辅助文件）。
在partial/_macros.html文件中，定义你的宏：
{# partial/_macros.html 内容 #}
{% macro article_card(article) %}
<div class="article-item">
<h3 class="article-title"><a href="{{ article.Link }}">{{ article.Title }}</a></h3>
{% if article.Description %}
<p class="article-description">{{ article.Description }}</p>
{% endif %}
<span class="article-date">{{ stampToDate(article.CreatedTime, "2006-01-02") }}</span>
</div>
{% endmacro %}
{% macro product_thumbnail(product) %}
<div class="product-thumb">
<a href="{{ product.Link }}">
<img src="{{ product.Thumb }}" alt="{{ product.Title }}" loading="lazy">
<p class="product-name">{{ product.Title }}</p>
</a>
</div>
{% endmacro %}
步骤2：在其他模板中引入并使用宏
在你的主模板文件（例如index.html或detail.html）中，使用{% import %}标签来引入宏文件。你可以一次性引入多个宏，也可以为宏指定别名。
{# index.html 内容 #}
{% import "partial/_macros.html" article_card, product_thumbnail as thumb_macro %}
{# ... 页面其他内容 ... #}
<h2>最新文章</h2>
<div class="articles-list">
{% archiveList latestArticles with type="list" moduleId=1 limit="3" %}
{% for item in latestArticles %}
{{ article_card(item) }} {# 调用 article_card 宏 #}
{% endfor %}
{% endarchiveList %}
</div>
<h2>推荐产品</h2>
<div class="products-grid">
{% archiveList featuredProducts with type="list" moduleId=2 limit="4" %}
{% for item in featuredProducts %}
{{ thumb_macro(item) }} {# 调用 product_thumbnail 宏的别名 thumb_macro #}
{% endfor %}
{% endarchiveList %}
</div>
通过{% import "partial/_macros.html" article_card, product_thumbnail as thumb_macro %}，我们引入了_macros.html文件中定义的article_card和product_thumbnail两个宏。其中，product_thumbnail宏被赋予了thumb_macro的别名，方便在当前模板中使用。
宏的作用域：与include的关键区别
需要特别注意的是，宏与{% include %}标签在变量作用域上有着本质区别。
{% include %}：会继承并可以直接访问调用它的父模板中的所有变量。{% macro %}：拥有自己的独立作用域。它只能访问通过参数明确传入的变量。这意味着，如果你在父模板中有一个global_setting变量，但在宏中没有将其作为参数传入，那么在宏内部是无法直接访问global_setting的。
这种设计使得宏更加独立和模块化，减少了意外的变量冲突，也使得宏的复用性更强，因为它不依赖于特定的外部环境。
**实践
- 明确命名：宏的名称应清晰地表达其功能或所渲染的组件。
- 单一职责：一个宏最好只负责渲染一个特定的组件或代码片段，避免功能过于复杂。
- 参数化：将所有可能变化的元素都通过参数传入，使宏更具灵活性。
- 存放约定：将所有宏文件统一放在
partial/目录下，便于管理和查找。 - 善用别名：在
import时为冗长的宏名设置简洁的别名，提高可读性。
通过熟练掌握宏的创建与应用，您将能够更高效、更优雅地进行安企CMS模板开发，构建出结构清晰、易于维护的高质量网站。
常见问题 (FAQ)
1. 宏能访问当前页面的所有变量吗？ 不能。宏有自己的独立作用域，它只能访问通过参数明确传入的变量。如果你需要在宏中使用父模板的某个变量，必须将其作为参数显式地传递给宏。
2. 宏和include标签有什么本质区别？我该如何选择？
主要区别在于变量作用域和使用场景：
*