在网站内容管理中，我们常常会遇到需要将相同的内容块，如页头、页脚、侧边栏或导航菜单，展示在多个页面上的情况。如果每次都复制粘贴这些代码，不仅效率低下，在需要修改时，更要面对在多个文件中重复操作的繁琐。长此以往，网站内容的维护和更新将变得异常困难，甚至容易出现不一致的体验。

幸运的是，安企CMS（AnqiCMS）为我们提供了优雅的解决方案，其中核心就是它模板引擎中的include标签。通过巧妙地运用include标签，我们可以轻松实现公共代码片段的引入和页面结构的复用，从而大大提升网站的开发和维护效率。

认识include标签的核心作用

include标签的本质，就是允许你在一个模板文件中，将另一个独立的HTML文件或代码片段引入进来。这就好比你在构建乐高模型时，不必每次都从头搭建一个相同的零件，而是可以预先组装好一些常用部件，然后在需要的时候直接拿来使用。在安企CMS中，这些可复用的代码片段通常会存放在模板目录下的partial/文件夹中，例如页头可以是partial/header.html，页脚可以是partial/footer.html。

这样做的好处显而易见：

  1. 代码集中管理：所有公共代码只需编写一次，存放在一个地方。
  2. 维护便捷高效：当公共部分需要调整时，只需修改一个文件，所有引用它的页面都会同步更新，避免了遗漏和不一致。
  3. 结构清晰可读：将页面拆分成独立的逻辑块，让模板结构更加清晰，易于理解和管理。

灵活运用include：从基本引入到动态内容

使用include标签非常直观，最基础的用法就是指定要引入的文件路径，例如：

{% include "partial/header.html" %}
{% include "partial/sidebar.html" %}
{% include "partial/footer.html" %}

这样，header.html、sidebar.html和footer.html中的内容就会被“嵌入”到当前模板文件中。

然而，仅仅静态引入有时不足以满足复杂的需求。我们可能希望同一个页头片段，在不同页面显示不同的标题，或者侧边栏根据当前页面类型加载不同的内容。这时，include标签提供的with和only参数就派上用场了。

  1. 通过with传递变量

    默认情况下，被include的模板片段会继承当前模板环境中的所有变量。但如果你想为引入的片段专门传入一些特定的数据，可以使用with参数。这使得你可以让公共片段变得更加动态和通用。

    例如，一个通用的页头片段可能需要显示一个动态的页面标题和关键词：

    {% include "partial/header.html" with title="当前页面标题" keywords="SEO关键词" %}

    而在partial/header.html中，就可以这样使用这些传入的变量：

    <!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{{title}} - {% system with name="SiteName" %}</title>
    <meta name="keywords" content="{{keywords}}">
    <!-- 其他页头内容 -->
</head>
<body>

    通过with，我们可以灵活地为每个引入的片段提供定制化的数据，而无需修改片段本身。

  2. 使用only控制变量作用域

    虽然继承所有变量很方便，但在某些情况下，我们可能希望被include的片段只访问通过with明确传递的变量，而不继承当前模板环境中的其他变量。这有助于避免潜在的变量冲突或不必要的依赖，让片段更加独立和可控。这时，只需在with参数后面加上only：

    {% include "partial/header.html" with title="当前页面标题" keywords="SEO关键词" only %}

    现在，partial/header.html将只能访问title和keywords这两个变量，而无法访问当前页面中定义的其他任何变量。

  3. 利用if_exists优雅处理不存在的片段

    有时候，你引入的模板片段可能并不是每个页面都必须存在的，或者在开发过程中，你可能不确定某个片段是否已经创建。直接引入一个不存在的文件会导致模板渲染错误。为了避免这种情况，可以使用if_exists参数：

    {% include "partial/optional_ad_section.html" if_exists %}

    如果partial/optional_ad_section.html文件存在，它就会被引入；如果不存在，安企CMS会静默地忽略这个include指令，而不会报错，确保页面的正常渲染。

模块化管理的进阶：extends和macro

除了include标签，安企CMS的模板系统还提供了extends和macro标签，它们在代码复用上各有侧重，共同构建了一个强大的模板体系。

  • extends标签：如果说include是“插入零件”，那么extends就是“继承骨架”。extends用于定义页面的整体布局或“母版”，通常包含页面的HTML结构、通用CSS/JS引用以及一些占位符（block），供子模板填充具体内容。例如，你可以定义一个base.html作为所有页面的基础布局，其中定义了header、content、footer等block区域。
  • macro标签：macro更像编程语言中的“函数”。它允许你定义可带参数的、可复用的小型HTML代码块。当你需要生成重复的、结构相似但内容不同的HTML片段时，macro会比include更具灵活性。例如，一个用于渲染文章列表项的macro可以接收文章对象作为参数，并根据参数生成相应的HTML。

通过将include用于独立的代码片段，extends用于页面整体布局，以及macro用于带参数的重复结构，我们可以将网站模板组织得井井有条，最大化代码的复用性，从而专注于高质量的内容创作和网站运营。安企CMS提供的这些模板功能，让网站的维护工作变得更加高效和智能。

常见问题解答 (FAQ)

Q1: include标签和extends标签有什么区别，我该如何选择？

A: include标签用于在当前模板的任何位置“插入”另一个模板片段的内容，就像把一张图片贴到画纸上一样，它适用于复用独立的、功能性的代码块，如导航菜单、侧边栏小部件等。而extends标签则用于定义页面的整体布局或“骨架”，它必须是模板文件的第一个标签，允许子模板“继承”并填充父模板中定义的block区域。简单来说，extends是自上而下的结构继承，定义了“这里应该有什么”，而include是横向的组件插入，定义了“这里需要一个这个东西”。当你想重用页面整体布局时用extends，当你想重用某个小块的代码时用include。

Q2: 我引入的模板片段中可以使用当前页面的数据（比如文档标题）吗？

A: 可以的。默认情况下，通过include标签引入的模板片段会自动继承当前模板环境中的所有变量。这意味着在header.html中，你可以直接访问当前页面的{{archive.Title}}或者{{category.Description}}等数据，前提是这些变量在引入时存在于当前模板上下文中。如果你想更精确地控制哪些变量可以被访问，可以使用with和only参数来明确指定或限制。

Q3: 如果我想在include的模板片段中动态传入一些变量，但又不想它访问当前页面的所有变量，应该怎么做？

A: 你可以使用with参数来传入特定的变量，并在with之后加上only关键词。例如：{% include "partial/my_component.html" with item_id=123 item_name="示例" only %}。这样，my_component.html模板就只能访问item_id和item_name这两个变量，而不会继承当前主模板中的其他任何变量，从而实现更严格的作用域控制和模块化。