如何在AnQiCMS模板中使用循环（for）标签遍历并显示内容列表？

在 AnQiCMS 模板中高效运用 for 循环标签展示内容列表，是构建动态网站不可或缺的核心技能。通过灵活运用 for 循环，我们可以轻松地遍历各种类型的数据集合，并以自定义的样式呈现在网站页面上，无论是新闻列表、产品展示、分类导航，还是其他任何重复性的内容区块，for 循环都能助你一臂之力。

接下来，我们将深入探讨如何在 AnQiCMS 模板中利用 for 循环标签，从基础用法到高级技巧，帮助你更好地组织和展示网站内容。

AnQiCMS 模板基础回顾

AnQiCMS 的模板系统借鉴了 Django 模板引擎的语法，整体简洁高效。在模板文件中，我们主要会遇到两种类型的标记：

  • 变量输出： 使用双大括号 {{ 变量名称 }} 来显示数据内容。例如，{{ item.Title }} 会输出列表项的标题。
  • 标签控制： 使用单大括号和百分号 {% 标签名称 参数 %} 来执行逻辑控制，比如条件判断、循环遍历等。所有控制标签都需要一个对应的结束标签，例如 {% if ... %} 对应 {% endif %}，{% for ... %} 对应 {% endfor %}。

理解这些基本语法是使用 for 循环的前提。

for 循环标签的核心作用

for 循环标签的作用在于遍历一个可迭代的对象（如数组、切片、列表），并在每次迭代中，将当前元素赋值给一个指定的变量，以便在循环体内访问和展示该元素的属性。这使得我们能够用一份模板代码，动态地渲染出多条内容。

它的基本结构通常是这样的：

{% for item in collection %}
    {# 在这里，你可以使用 item 变量来访问当前遍历到的数据项的属性 #}
    {{ item.Property1 }}
    {{ item.Property2 }}
{% endfor %}

在这里，collection 是一个包含了多个数据项的列表，item 则是每次循环中代表当前数据项的临时变量。

for 循环的基本用法与示例

在 AnQiCMS 中，各种内容列表标签（如 archiveList 文档列表、categoryList 分类列表、pageList 单页面列表等）都会返回一个可供 for 循环遍历的数据集合。让我们以一个常见的需求为例：展示最新发布的文档列表。

首先，我们需要使用 archiveList 标签来获取文档集合。假设我们想获取 ID 为 1 的分类下的最新 5 篇文档：

{% archiveList documents with type="list" categoryId="1" limit="5" %}
    {% for doc in documents %}
        <div>
            <h3><a href="{{ doc.Link }}">{{ doc.Title }}</a></h3>
            <p>{{ doc.Description }}</p>
            <p>发布时间: {{ stampToDate(doc.CreatedTime, "2006-01-02") }}</p>
            <img src="{{ doc.Thumb }}" alt="{{ doc.Title }}">
        </div>
    {% endfor %}
{% endarchiveList %}

在这个例子中：

  • {% archiveList documents with ... %} 获取了一个名为 documents 的文档集合。
  • {% for doc in documents %} 开始遍历这个集合，每次迭代将当前文档赋值给 doc 变量。
  • 在循环体内，我们通过 {{ doc.Link }}、{{ doc.Title }}、{{ doc.Description }}、{{ doc.Thumb }} 等访问当前文档的链接、标题、描述和缩略图。
  • {{ stampToDate(doc.CreatedTime, "2006-01-02") }} 则展示了如何使用 stampToDate 辅助标签将文档的创建时间戳格式化为可读的日期。

增强 for 循环的实用技巧

for 循环不仅限于简单遍历，它还提供了一些非常有用的辅助功能和高级用法，让你的内容展示更加灵活。

1. 处理空列表 (empty 语句块)

当数据集合可能为空时，for 循环的 empty 语句块可以提供友好的提示信息，而不是显示一个空白区域。这对于提升用户体验至关重要。

{% archiveList documents with type="list" categoryId="999" limit="5" %}
    {% for doc in documents %}
        <div>
            <h3><a href="{{ doc.Link }}">{{ doc.Title }}</a></h3>
            <p>...</p>
        </div>
    {% empty %}
        <p>抱歉，当前分类下暂无文档。</p>
    {% endfor %}
{% endarchiveList %}

如果 documents 集合是空的，页面就会显示“抱歉，当前分类下暂无文档。”这条提示。

2. 获取循环序号与反向序号 (forloop 变量)

在循环体内，系统会自动提供一个特殊的 forloop 变量，它包含了当前循环的一些有用信息：

  • forloop.Counter: 当前迭代的从 1 开始的序号。
  • forloop.Revcounter: 当前迭代的从集合总数开始的反向序号。

这在需要为列表项添加序号、或者为偶数/奇数行应用不同