在构建一个网站时，我们常常会遇到这样的场景：网站的页头（Header）、页脚（Footer）、侧边栏（Sidebar）以及导航菜单等模块，几乎在每个页面都会出现。这些模块不仅内容相似，而且其结构和样式也需要保持高度一致。如果为每个页面都重复编写这些代码，不仅效率低下，后续一旦需要修改，就得逐一调整所有页面，这无疑是一场维护的噩梦。

幸运的是，安企CMS（AnQiCMS）深知模板复用的重要性，并提供了强大而灵活的include标签，让这一切变得简单高效。通过include标签，我们可以将这些公共模块独立成单独的文件，然后在任何需要它们的地方轻松引用，从而极大提升开发效率、降低维护成本，并确保网站整体风格的统一性。

include标签的核心价值

include标签的核心理念是“一次编写，多处引用”。它允许开发者将一块独立的模板代码（例如页头、页脚的HTML结构）提取出来，保存为一个单独的模板文件。当其他模板需要这部分代码时，只需使用include标签指向该文件，系统就会在渲染页面时将这部分代码“插入”到指定位置。

这种复用模式带来了多重益处：

  1. 提高开发效率： 无需复制代码，只需简单一行标签即可引入复杂模块。
  2. 降低维护成本： 公共模块的任何修改都只需在一处进行，所有引用它的页面都会自动更新。
  3. 保持代码整洁： 页面模板只包含核心内容和必要的include语句，结构清晰易读。
  4. 确保视觉一致性： 保证了网站不同页面上公共元素的统一外观和功能。

include标签的基础用法

在安企CMS的模板系统中，include标签的使用方式非常直观。假设我们已经将网站的公共页头内容保存为partial/header.html，公共页脚内容保存为partial/footer.html，它们通常位于当前模板主题的根目录下（例如template/default/partial/）。那么，在任何一个页面模板中（比如index.html、detail.html），我们只需这样引用它们：

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

<!-- 这里是当前页面的主要内容 -->

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

当页面被访问时，安企CMS会自动找到并加载partial/header.html和partial/footer.html中的内容，然后将其无缝地呈现在当前页面的相应位置。

更灵活的用法：传递变量

仅仅是简单地包含文件，有时还不足以应对所有需求。例如，网站的页头可能需要显示当前页面的标题，或者页脚的版权信息需要根据不同页面动态调整。这时，include标签的with关键字就派上用场了。它允许我们向被引入的模板传递特定的变量。

假设我们的partial/header.html中包含了一个{{ pageTitle }}变量，用于显示页面标题：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{{ pageTitle }} - 你的网站名称</title>
    <!-- 其他头部信息 -->
</head>
<body>
    <header>
        <h1>{{ pageTitle }}</h1>
        <!-- 导航等 -->
    </header>
    <main>

那么，在引用header.html的页面中，我们可以这样传递pageTitle变量：

{% include "partial/header.html" with pageTitle="安企CMS文章详情" %}

<!-- 文章详情内容 -->

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

这样，partial/header.html在渲染时，{{ pageTitle }}就会被替换为“安企CMS文章详情”。你也可以同时传递多个变量，只需用空格分隔：

{% include "partial/header.html" with pageTitle="安企CMS文章详情" keywords="安企CMS, 模板, 详情" %}

控制变量作用域：only关键字

默认情况下，使用include标签引入的模板会继承父模板的所有变量。这在大多数情况下是方便的，但有时我们可能只想让被引入的模板使用我们通过with明确传递的变量，而不继承父模板的任何其他变量，以避免潜在的变量冲突或不必要的复杂性。这时，可以使用only关键字来限制变量的作用域：

{% include "partial/header.html" with pageTitle="安企CMS文章详情" only %}

通过添加only，partial/header.html将只能访问pageTitle这个变量，而无法访问当前页面模板中定义的其他变量。这有助于保持模块的独立性和可预测性。

健壮性考量：处理不存在的模板

在某些情况下，你可能不确定被include的模板文件是否存在，或者某个模块是可选的。如果强制include一个不存在的文件，系统可能会报错。为了避免这种情况，可以使用if_exists关键字：

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

如果partial/sidebar.html文件存在，它会被正常引入；如果不存在，则该include语句会被忽略，页面渲染不会受到影响，也不会报错。这使得你的模板在面对不完整或可选模块时更加健壮。

实践建议与**实践

为了充分发挥include标签的优势，以下是一些实践建议：

  • 约定俗成的目录结构： 建议将所有可复用的代码片段（如页头、页脚、导航、侧边栏、评论区、面包屑等）统一存放在当前模板主题目录下的partial/子目录中。这有助于保持模板文件的组织结构清晰，方便查找和管理。
  • 细粒度拆分： 不要害怕将大型公共模块进一步拆分为更小的、可管理的片段。例如，一个复杂的页头可以拆分成“logo区”、“主导航”、“用户登录状态”等多个小模块，再在header.html中include它们。
  • 文档化你的模块： 对于复杂的或带有特定参数的include模块，最好在文件内部添加注释，说明其功能和所需变量，方便其他开发者理解和使用。

include标签是安企CMS模板开发中一个极其有用且灵活的特性。它鼓励模块化设计，大幅提升了模板的复用性，使得网站的构建和维护工作变得更加轻松高效。掌握并善用这一工具，你的安企CMS网站模板将更具可维护性和扩展性。

常见问题解答 (FAQ)

  1. include标签和extends标签有什么区别？ include标签用于将一个模板文件（通常是小片段，如页头、页脚或导航）的内容插入到另一个模板的特定位置，类似于代码复用。被include的模板可以访问父模板的变量，也可以通过with传递自己的变量。 而extends标签用于模板继承，它定义了一个基础布局（父模板），其中包含用block标签定义的区域。子模板可以重写这些block区域来填充具体内容，但其整体结构和大部分内容都继承自父模板。extends必须是子模板中的第一个标签，并且子模板的结构完全依赖于父模板的定义。

  2. 我能在include引入的模板中使用哪些变量？ 默认情况下，include引入的模板会继承父模板的所有变量。这意味着，在父模板中定义的任何变量，都可以在被引入的模板中直接使用。 此外，你还可以使用with关键字显式地向被include的模板传递新的变量，这些变量可以在被引入的模板中直接使用。如果同时使用了only关键字，那么被include的模板将只接收通过with传递的变量，而不会继承父模板的任何其他变量。

  3. include标签中的模板路径是相对路径还是绝对路径？如何指定？ include标签中的路径是相对于当前模板文件所在的模板主题根目录的相对路径。例如，如果你的当前模板主题目录是/template/default/，而你想要引入的文件是/template/default/partial/header.html，那么在include标签中应写为"partial/header.html"。安企CMS的模板系统会根据你当前启用的模板主题来解析这些相对路径，因此无需指定完整的绝对路径。