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

在AnQiCMS的模板开发中，掌握如何有效地展示动态数据列表是构建一个功能丰富网站的关键。无论是最新文章、产品展示，还是分类导航，这些都离不开模板中的循环机制。AnQiCMS的模板系统借鉴了Django模板引擎的简洁与强大，其中的for循环标签便是实现数据遍历的核心工具。

理解for循环标签的基础

当我们需要在页面上重复展示一系列结构相似的数据时，for循环就派上了用场。它的基本语法非常直观：{% for item in collection %} ... {% endfor %}。这里，collection代表你想要遍历的数据集合，它可以是系统提供的各种数据列表（如文章列表、产品列表），而item则是一个临时变量，在每一次循环中会指向collection中的一个数据项。通过item，我们就可以访问该数据项的各个属性，并在页面上进行呈现。

核心数据获取：以archiveList为例

在AnQiCMS中，获取数据列表通常会用到特定的标签，其中最常用也最全面的就是archiveList标签。它能够帮助我们从数据库中检索出各种类型的文档（文章、产品等），并支持灵活的筛选和排序。

使用archiveList时，我们通常会结合多个参数来精确控制所需的数据：

  • moduleId：这个参数用于指定你想要获取哪个内容模型的文档。例如，如果你想获取文章列表，可能会设置moduleId="1"（假设文章模型ID为1）；如果是产品列表，则设置对应的产品模型ID。
  • categoryId：如果你只想显示特定分类下的文档，可以使用这个参数指定分类的ID。也可以传入多个ID用逗号分隔，获取多个分类的文档。特别地，如果你不指定categoryId，它会尝试获取当前页面的分类ID，如果你想明确不自动读取，可以设置为categoryId="0"。
  • type：这个参数非常重要，它决定了列表的类型。type="list"通常用于获取固定数量的数据列表（例如首页的热门推荐）；而type="page"则用于需要分页显示的大型列表，它会与后续的分页标签pagination协同工作。
  • limit：用于控制显示的数据数量。当你使用type="list"时，可以直接设置一个数字，如limit="10"。更灵活的是，它还支持offset模式，比如limit="2,10"表示从第3条数据开始，获取10条数据。
  • order：数据以何种方式排序？你可以选择order="id desc"按ID降序（最新发布）、order="views desc"按浏览量降序（最热门），或者order="sort desc"按后台设定的自定义排序。

当我们使用archiveList标签获取数据时，通常会将其结果赋给一个变量，例如archives： {% archiveList archives with moduleId="1" type="list" limit="5" order="id desc" %}

结合for标签遍历并显示数据

有了数据集合，接下来就是使用for循环将其展示在页面上。让我们看一个典型的文章列表示例：

<div class="article-list">
    {% archiveList articles with moduleId="1" type="list" limit="5" order="id desc" %}
        {% for item in articles %}
        <div class="article-item">
            <a href="{{ item.Link }}" class="article-title">{{ item.Title }}</a>
            <div class="article-meta">
                <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                <span>浏览量：{{ item.Views }}</span>
            </div>
            {% if item.Thumb %}
            <div class="article-thumb">
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}">
            </div>
            {% endif %}
            <p class="article-description">{{ item.Description }}</p>
        </div>
        {% empty %}
        <p>暂时没有文章发布。</p>
        {% endfor %}
    {% endarchiveList %}
</div>

在这个例子中：

  1. 我们首先使用archiveList获取了最新的5篇文章（moduleId="1"，limit="5"，order="id desc"），并将结果存储在articles变量中。
  2. 接着，{% for item in articles %}开始遍历articles这个列表。每一次循环，item就代表了一篇文章的所有信息。
  3. 在循环内部，我们通过{{ item.Link }}获取文章链接，{{ item.Title }}获取文章标题，{{ item.Views }}获取浏览量。
  4. 注意到发布日期{{ stampToDate(item.CreatedTime, "2006-01-02") }}，这里使用了stampToDate过滤器来将原始的时间戳格式化为我们更易读的“年-月-日”形式。
  5. {% if item.Thumb %}则是一个简单的条件判断，只有当文章存在缩略图时，才会显示图片。
  6. 最重要的是{% empty %}标签，它提供了当articles列表为空时，页面上显示的内容，避免了空白页面的尴尬，提升了用户体验。

循环中的辅助信息：forloop对象

在for循环内部，AnQiCMS还提供了一个特殊的forloop对象，它能提供当前循环的上下文信息，这对于实现一些特殊样式或逻辑非常有用：

  • forloop.Counter：表示当前循环的索引，从1开始计数。
  • forloop.Revcounter：表示当前循环的倒序索引，从列表总数开始倒数，到1结束。 例如，你可能想给列表中的第一个元素添加一个active的CSS类： {% for item in articles %} <li class="{% if forloop.Counter == 1 %}active{% endif %}">...</li> {% endfor %}

其他列表标签的通用性

除了archiveList，AnQiCMS还提供了许多其他获取数据列表的标签，它们的使用方式与archiveList非常相似，都是通过赋予一个变量，再结合for循环来遍历：

  • categoryList：用于获取文章或产品的分类列表。
  • pageList：获取单页列表（如“关于我们”、“联系我们”等页面）。
  • tagDataList：获取特定Tag下的文档列表。
  • navList：获取网站导航菜单列表，通常用于构建顶部或底部导航。
  • bannerList：获取网站的Banner图片列表，常用于轮播图。
  • linkList：获取友情链接列表。

掌握了archiveList和for循环的用法，你可以轻松地将这些标签生成的数据呈现在网站的各个角落，从而构建出动态且内容丰富的页面。AnQiCMS强大的模板功能，正是通过这种直观的标签组合，让网站内容的运营和展示变得高效而灵活。

常见问题 (FAQ)

Q1: 为什么我的for循环没有输出任何内容，也没有显示{% empty %}里的备用文本？

A1: 如果for循环内既没有输出数据，也没有显示empty文本，这通常意味着你在{% archiveList ... %}（或任何其他列表标签）中定义的变量名与{% for item in ... %}中使用的变量名不一致。例如，你可能定义了{% archiveList documents ... %}，但循环时写成了{% for item in archives %}。请务必检查变量名是否完全匹配。

Q2: 如何在for循环中根据数据项的某个属性值，显示不同的内容或样式？

A2: 你可以使用if逻辑判断标签在for循环内部实现条件渲染。例如，如果你想给文章标题特别长的文章加上一个省略号，或者给某个特定ID的文章添加一个“置顶”标记，可以这样做：

{% for item in articles %}
    <div class="article-item">
        {% if item.Title|length > 30 %}
            <h3 class="long-title">{{ item.Title|truncatechars(30) }}...</h3>
        {% else %}
            <h3>{{ item.Title }}</h3>
        {% endif %}

        {% if item.Id == 123 %} {# 假设ID为123的文章是置顶文章 #}
            <span class="sticky-tag">置顶</span>
        {% endif %}
        {# 其他内容 #}
    </div>
{% endfor %}

这里item.Title|length和item.Title|truncatechars(30)是使用了AnQiCMS内置的字符串过滤器来获取长度和截断字符串。

Q3: archiveList的limit参数和分页标签pagination有什么区别，应该如何选择？

A3: limit参数用于限制单次获取的数据数量。当你希望在一个页面上显示固定数量的数据，例如“最新推荐5篇文章”、“热门产品10个”时，适合使用limit配合type="list"。而pagination标签则用于处理需要分多页显示大量数据的情况。当你设置archiveList的type="page"时，系统会自动计算总页数和当前页码，pagination标签会利用这些信息生成页码链接，让用户可以在不同页面之间跳转。简而言之，limit是数量限制，pagination是页面导航，两者结合使用（type="page"必须搭配pagination）才能实现完整的分页功能。