如何在AnqiCMS模板中使用with或set标签定义变量，以优化内容显示和维护？

在AnqiCMS的模板开发中，为了让我们的网站内容展示更加灵活、代码更易维护，变量的定义和使用是不可或缺的技巧。系统采用的是类似Django模板引擎的语法，其中with和set标签就是我们定义变量，优化内容显示和管理模板的得力助手。理解并善用它们，能让您的网站运营事半功倍。

为什么我们需要在模板中定义变量？

想象一下，您的网站有多个页面需要显示相同的公司电话号码或版权信息，或者在某个特定的内容区块中，您需要对数据进行一些临时的计算或格式化。如果每次都直接把信息写死在模板里，或者重复编写相同的处理逻辑，那么当信息需要更新时，您就得逐一修改每个页面，这不仅效率低下，还容易出错。

在模板中定义变量，可以帮助我们：

  1. 提升代码可读性与整洁度： 将复杂的数据处理或重复值抽象成有意义的变量名，让模板代码一目了然。
  2. 增强内容可维护性： 集中管理关键信息，一旦需要修改，只需在一个地方更新变量定义即可。
  3. 促进模板复用： 结合include等标签，通过变量传递动态内容，让通用的模板片段适应不同的显示需求。
  4. 优化内容显示逻辑： 对从后台获取的数据进行二次处理，确保前端展示符合预期，避免直接在HTML中硬编码逻辑。

接下来，我们就深入了解set和with这两个标签的具体用法和适用场景。

set：定义局部变量的利器

set标签用于在当前模板文件内定义一个局部变量，这个变量的生命周期仅限于它被定义和使用的当前模板区块。它非常适合处理临时的计算结果、中间数据或者在循环中对某个值进行暂存。

基本用法：

您可以通过{% set 变量名 = 表达式 %}的方式来定义变量。例如，如果您想暂存一个计算结果：

{% set total_items = archiveList.length + pageList.length %}
<p>网站共有 {{ total_items }} 篇文章和页面。</p>

在这个例子中，total_items变量只在当前模板中有效，方便您在接下来的内容中引用。

set标签的变量也可以在不同的作用域（如block或for循环）中被重新赋值，但这种赋值通常只在该作用域内生效，不会影响外部同名变量的值，除非是在某些特定场景下（例如在继承模板中）。

{% set site_title = "AnqiCMS演示站" %}

<header>
    <h1>{{ site_title }}</h1>
</header>

{% block content %}
    {% set section_title = "最新文章" %}
    <p>当前板块标题：{{ section_title }}</p>
    {# ... 文章列表内容 ... #}
{% endblock %}

<footer>
    <p>版权所有 © {{ site_title }}</p> {# 这里的 site_title 仍然是 "AnqiCMS演示站" #}
</footer>

可以看到，section_title只在content区块内生效。这种局部性使得set成为管理模板内部变量的理想选择，有助于避免不同模板片段间的变量名冲突。

with：跨模板和局部共享变量的桥梁

with标签则提供了一种在特定代码块内或者向被包含（include）的模板文件传递变量的方式。它创建了一个临时的变量作用域，当with代码块结束时，这些临时变量就会被清除。with标签尤其适用于您需要为某一段特定的内容提供一组变量，或者向一个公共的模板片段（如头部、侧边栏）传递动态数据。

基本用法：

with标签需要与endwith标签成对使用，它包裹的代码块内的变量定义对该区块和其内部包含的模板文件可见。

{% with welcome_message="欢迎来到我们的网站！" site_slogan="您的内容管理专家" %}
    <header>
        <h1>{{ welcome_message }}</h1>
        <p>{{ site_slogan }}</p>
    </header>
{% endwith %}

{# 这里访问 welcome_message 或 site_slogan 将会出错，因为它们的作用域已结束 #}

with标签最常见的用途是配合include标签，向被包含的模板文件传递参数。这让您的通用模板片段（例如一个通用的文章卡片组件或导航菜单）能够接收不同的数据，实现高度复用。

假设您有一个partial/article_card.html的模板片段：

{# partial/article_card.html #}
<div class="article-card">
    <img src="{{ card_image }}" alt="{{ card_title }}">
    <h3><a href="{{ card_link }}">{{ card_title }}</a></h3>
    <p>{{ card_description }}</p>
</div>

您可以在主模板中这样引用并传递数据：

{% include "partial/article_card.html" with
    card_image=item.Thumb
    card_title=item.Title
    card_link=item.Link
    card_description=item.Description
%}

通过with传递变量，article_card.html模板片段就能在不同的文章列表或详情页中被复用，显示不同的文章信息，极大地提高了模板的模块化程度和可维护性。您甚至可以使用only关键字限制include只接受通过with传递的变量，避免意外的全局变量干扰。

{% include "partial/header.html" with title="我的自定义标题" keywords="SEO关键词" only %}

这将确保header.html中只能访问title和keywords这两个变量。

set 与 with：何时选择哪一个？

选择set还是with，主要取决于变量的作用域需求和使用场景：

  • 选择 set 当：

    • 您需要在一个模板文件内部，为某个小范围的逻辑（如一个循环或一个区块）定义一个临时变量。
    • 变量不需要传递给被包含的模板文件，或者被包含的模板文件会通过其他更通用的方式（如上下文变量）获取数据。
    • 您需要进行一些临时的数值计算、字符串拼接或数据转换，并将结果存储起来供后续使用。

  • 选择 with 当：

    • 您需要为模板中的一个特定区块创建一组临时的变量上下文。
    • 您要向一个通过include标签引入的通用模板片段传递明确的、动态的参数。这是with标签最核心的优势所在，它能让您的模板组件更具“插拔”性。
    • 您希望变量的作用域被严格限制在{% with %}和{% endwith %}之间，避免影响外部环境。

实际应用场景举例

在AnqiCMS的日常运营中，set和with标签的应用无处不在：

  1. 统一网站头部信息： 假设您的网站头部header.html需要动态显示当前页面的标题（可能包含分类名、文章名等），并根据不同的页面设置不同的SEO关键词和描述。您可以在主页面中通过set或从AnqiCMS的tdk标签获取这些值，然后用with将它们传递给header.html。

    {# 在某个详情页模板中 #}
{% tdk page_title with name="Title" siteName=true %}
{% tdk page_keywords with name="Keywords" %}
{% tdk page_description with name="Description" %}


{% include "partial/header.html" with title=page_title keywords=page_keywords description=page_description %}

  2. 动态侧边栏或广告位： 网站的侧边栏通常会展示热门文章、最新产品或广告。您可以定义一个通用的partial/sidebar.html，然后根据不同的页面类型（文章详情页、产品列表页）通过with传递不同的category_id或module_id，让侧边栏动态加载相关内容。

  3. 内容格式化与展示： 从AnqiCMS后台获取的文章内容可能包含原始HTML，您可能需要在显示前进行一些字符截断或者图片懒加载处理。set可以在模板内部快速处理这些逻辑，再将处理后的变量用于最终展示。