如何在AnQiCMS模板中引入外部HTML片段（include）？
在AnQiCMS中构建网站模板时，我们常常会遇到一些需要重复使用的HTML代码块，比如网站的页头、页脚、侧边栏导航、广告位或者是一些通用的内容模块。如果每次都在不同的模板文件中重复编写这些代码，不仅效率低下，而且一旦需要修改，就得逐个文件去查找和更新，维护起来会非常麻烦。
为了解决这个问题，AnQiCMS提供了强大的模板功能，其中就包括了引入外部HTML片段的能力，这让网站模板的开发变得更加灵活和高效。
核心功能：轻松引入外部HTML片段
AnQiCMS的模板系统基于类似Django的语法，它允许您使用include标签，将一个独立的HTML文件内容嵌入到另一个模板文件中。这个功能的核心价值在于“复用”，您可以把那些公共的、需要在多个页面上显示的部分抽取出来，做成一个独立的HTML文件，然后在需要的地方简单地引用它。
通常，这些可复用的HTML片段文件都以.html作为后缀，并且推荐存放在您的模板目录下的partial/子文件夹中。比如，您有一个名为default的模板，它的根目录是/template/default/，那么您可以创建一个/template/default/partial/目录，专门用来存放这些代码片段。
最基础的引入方式非常直观，就像这样：
{# 假设您的模板文件是 index.html #}
{% include "partial/header.html" %}
<main>
<h1>欢迎来到我的网站</h1>
<!-- 这里是页面特有的内容 -->
</main>
{% include "partial/footer.html" %}
在上面的例子中，header.html和footer.html就是两个外部HTML片段。它们可能包含了网站的logo、主导航、版权信息等公共元素。
一个简单的partial/header.html可能长这样：
<header class="site-header">
<div class="container">
<a href="/" class="logo">
<img src="/static/images/logo.png" alt="网站Logo">
</a>
<nav class="main-nav">
<ul>
<li><a href="/">首页</a></li>
<li><a href="/about">关于我们</a></li>
<li><a href="/contact">联系我们</a></li>
</ul>
</nav>
</div>
</header>
这样一来，无论哪个页面需要页头，只需要一行{% include "partial/header.html" %}就能搞定，大大提升了开发效率和后期维护的便利性。
进阶用法：向片段传递数据
很多时候，被引入的HTML片段不仅仅是静态内容，它可能也需要显示一些动态信息。例如，一个侧边栏可能需要展示当前页面的标题，或者一个通用的卡片组件需要根据不同的数据来填充。AnQiCMS允许您在使用include标签时，通过with关键字向被引入的片段传递变量。
例如，您可能有一个partial/sidebar.html，它需要一个current_title变量来显示当前页面信息：
<aside class="sidebar">
<h3>当前页面</h3>
<p>{{ current_title }}</p>
<ul class="recent-posts">
<!-- 这里可能还有其他动态内容，比如最新文章列表 -->
</ul>
</aside>
在您的主模板文件中，您可以这样向sidebar.html传递数据：
{# 假设您的模板文件是 article_detail.html #}
{% include "partial/header.html" %}
<main>
<h1>文章详情页</h1>
<div class="content">
<!-- 文章内容 -->
</div>
</main>
{% include "partial/sidebar.html" with current_title="AnQiCMS模板开发指南" %}
{% include "partial/footer.html" %}
您还可以传递多个变量，只需用空格隔开即可：
{% include "partial/product_card.html" with product_name="AnQiCMS企业版" price="￥999" discount="8折" %}
在某些场景下，您可能希望被引入的片段只能访问您明确传递的变量，而不能访问主模板中的其他变量。这时，可以在with后面加上only关键字：
{% include "partial/ad_banner.html" with ad_id="promo_123" ad_type="image" only %}
使用了only之后，ad_banner.html就只能使用ad_id和ad_type这两个变量，而不会受到主模板中其他变量的干扰，这有助于保持代码片段的独立性和避免潜在的命名冲突。
处理不存在的模板文件
在开发过程中，偶尔会遇到引入的模板文件路径错误或者文件被删除的情况，这可能导致页面报错。为了提高模板的健壮性，您可以使用if_exists关键字。
当您使用if_exists时，如果指定的模板文件不存在，AnQiCMS会优雅地忽略这个include语句，而不会导致整个页面渲染失败。这在一些非核心、可选性的代码片段中特别有用。
{# 尝试引入一个可能存在的广告位，如果不存在也不会报错 #}
{% include "partial/optional_ad.html" if_exists %}
<main>
<h1>页面主内容</h1>
</main>
{# 尝试引入一个可能存在的推荐文章模块 #}
{% include "partial/recommended_articles.html" if_exists with category_id="1" %}
使用小贴士与**实践
- 模块化思维： 在设计模板时，尽量将页面划分为逻辑清晰、功能独立的模块，每个模块对应一个HTML片段。
- 清晰的目录结构： 始终建议将所有可复用的片段放在一个统一的
partial/目录下，并根据功能进一步细分，例如partial/nav/main_menu.html，partial/widgets/search_box.html。 - 避免过度嵌套： 虽然可以无限嵌套
include，但过深的嵌套可能会让模板结构变得复杂，不利于理解和调试。尽量保持片段的扁平化。 - 合理使用
extends与include：extends标签通常用于定义页面的整体布局骨架（如base.html），包含头部、侧边栏、主体内容区域等大的结构，而include则用于填充或插入这些结构中的具体小组件或内容块。两者相辅相成，共同构建出高效的模板体系。 - 为片段添加注释： 在复杂的片段文件开头添加简要注释，说明其功能、所需变量等，方便团队协作和未来维护。
通过巧妙运用AnQiCMS的include功能，您可以让网站的模板开发变得更加有条理、易于管理，并显著提升开发和维护效率。
常见问题 (FAQ)
1. include和extends标签有什么区别？
extends标签用于实现模板继承，它定义了一个页面的整体骨架或布局，并允许子模板重写其中的特定“块”（block）。通常，一个页面只会extends一个父模板。而include标签则用于在任何模板（包括父模板和子模板）中插入一个独立的HTML片段。可以把它理解为将一个小的代码文件“复制粘贴”到当前位置。extends是定义页面的“形状”，include是填充页面的“内容块”。
2. 我可以在引入的HTML片段中使用AnQiCMS的标签和变量吗？
是的，完全可以。AnQiCMS的模板系统会将当前模板的上下文（所有可用的变量和标签）传递给被include的片段。这意味着您可以在include的片段中像在主模板中一样，自由使用AnQiCMS提供的各种标签（如archiveList、system等）以及传递给片段或继承自父模板的变量。
3. 引入的HTML片段文件必须放在partial/目录下吗？
不是必须的，这是一个推荐的**实践。您可以将HTML片段文件放置在模板目录的任何子文件夹中，只要include标签中提供的路径是相对于当前模板目录的正确路径即可。例如，如果您的片段在my_components/widget.html，那么您可以写{% include "my_components/widget.html" %}。但为了保持项目结构清晰，方便管理，强烈建议将常用片段统一归类到partial/目录下。