如何在AnQiCMS模板中循环遍历并输出文章列表？

AnQiCMS 为网站内容管理提供了强大而灵活的模板系统，其中，循环遍历并输出文章列表是构建动态网站不可或缺的核心功能。无论您是需要展示最新文章、分类列表，还是实现高级筛选和分页，AnQiCMS 的模板标签都能帮助您高效完成。

核心功能：理解 archiveList 标签

在 AnQiCMS 的模板中，获取并展示文章列表的关键在于使用 archiveList 标签。这个标签是功能强大的数据提取工具，允许您根据各种条件筛选、排序和限制文章的输出。

archiveList 标签的基本语法结构是 {% archiveList 变量名称 with 参数... %}...{% endarchiveList %}。您需要为获取到的文章列表指定一个变量名（例如 archives），随后的 with 关键字则用于传递各种筛选参数。

常见的 archiveList 参数包括：

  • moduleId：指定您想要获取的文章所属的内容模型 ID。例如，如果您要获取普通的文章列表，通常会设置 moduleId="1"（文章模型的默认 ID）；如果需要产品列表，可能是 moduleId="2"。
  • categoryId：根据文章所属的分类 ID 进行筛选。您可以指定单个分类 ID，也可以使用逗号分隔的多个 ID，例如 categoryId="1,3,5" 来获取来自多个分类的文章。如果希望获取当前页面分类下的文章，通常不需要指定此参数，系统会智能判断；但如果明确不希望读取当前分类，可设置为 categoryId="0"。
  • limit：控制文章列表的显示数量。例如 limit="10" 将只显示 10 篇文章。它还支持 offset 模式，通过逗号分隔来指定从第几条开始获取以及获取的数量，如 limit="2,10" 表示从第 3 条文章开始获取 10 条。
  • type：定义列表的类型，这对于分页功能尤其重要。type="list" 将按照 limit 参数指定的数量直接输出列表；而 type="page" 则表示您希望启用分页功能，这将与后续的分页标签 pagination 配合使用。
  • order：设置文章的排序规则。常用的排序方式有：order="id desc"（按 ID 降序，即最新发布）、order="views desc"（按浏览量降序，即最热门）、order="sort desc"（按后台自定义排序，默认值）。
  • q：用于关键词搜索。当 type="page" 时生效，可以指定一个搜索关键词来过滤文章列表，例如 q="SEO优化"。如果 URL 中包含 q=关键词 的查询参数，系统也会自动识别并应用。
  • siteId: 在多站点环境下，如果您需要获取其他站点的数据，可以通过指定 siteId 来实现。

循环遍历与内容输出：逐步实现文章列表

当我们通过 archiveList 标签成功获取到文章数据集合后，接下来就是使用 {% for ... in ... %} 循环标签，将这些数据逐一展示在页面上。

假设我们希望在首页展示一个最新的文章列表，每篇文章包含标题、链接、简介、缩略图，并显示其所属分类和发布日期。以下是一个实现此功能的代码示例：

<div class="latest-articles">
    <h2>最新文章</h2>
    <ul>
        {% archiveList archives with moduleId="1" type="list" order="id desc" limit="10" %}
            {% for item in archives %}
            <li class="article-item">
                <a href="{{ item.Link }}" class="article-link">
                    {% if item.Thumb %}
                        <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="article-thumb">
                    {% endif %}
                    <div class="article-info">
                        <h3 class="article-title">{{ item.Title }}</h3>
                        <p class="article-description">{{ item.Description }}</p>
                        <div class="article-meta">
                            <span class="article-category">分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
                            <span class="article-date">发布于：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                            <span class="article-views">浏览量：{{ item.Views }}</span>
                        </div>
                    </div>
                </a>
            </li>
            {% empty %}
            <li class="no-content">
                目前还没有任何文章发布，敬请期待！
            </li>
            {% endfor %}
        {% endarchiveList %}
    </ul>
</div>

在这个示例中：

  1. 我们首先使用 archiveList 标签，将文章模型 ( moduleId="1" ) 下的最新 10 篇文章 (order="id desc" limit="10") 赋值给 archives 变量。
  2. 接着，{% for item in archives %} 循环会遍历 archives 中的每一篇文章，并将当前文章的数据赋值给 item 变量。
  3. 在循环内部，我们可以通过 item.字段名 的方式访问文章的各项属性，例如 item.Title 获取标题，item.Link 获取链接，item.Description 获取简介。
  4. item.Thumb 提供了文章的缩略图路径，我们将其作为 <img> 标签的 src 属性，并结合 {% if item.Thumb %} 进行判断，避免没有缩略图时出现图片占位符。
  5. 文章发布日期 item.CreatedTime 是一个时间戳，我们使用了 {{ stampToDate(item.CreatedTime, "2006-01-02") }} 辅助标签将其格式化为易读的日期字符串（AnQiCMS 使用 Go 语言的日期格式化标准，”2006-01-02” 是一个常用的格式化模板）。
  6. 为了获取文章所属分类的名称，我们利用了 item.CategoryId，并将其作为参数传递给 {% categoryDetail with name="Title" id=item.CategoryId %} 标签，从而在文章列表中显示分类名称。
  7. 最后，{% empty %} 标签提供了一个优雅的方式来处理文章列表为空的情况，它会在 archives 没有任何内容时显示预设的提示信息，而不是空白页面。

高级应用：列表筛选与分页

对于需要更多交互性和数据量的场景，AnQiCMS 也提供了完善的解决方案。

如果您希望用户能够浏览多页文章，而不是一次性加载所有内容，可以将 archiveList 的 type 参数设置为 type="page"。此时，您需要额外配合 pagination 标签来生成分页导航：

”`twig {# 假设这是文章列表页模板 article/list.html #} 

{% archiveList archives with moduleId="1" type="page" order="id desc" limit="10" %}
    {# 循环输出文章列表内容，结构与上面示例类似 #}
    {% for item in archives %}
        <li class="article-item">
            <a href="{{ item.Link }}" class="article-link">
                {% if item.Thumb %}
                    <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="article-thumb">
                {% endif %}
                <div class="article-info">
                    <h3 class="article-title">{{ item.Title }}</h3>
                    <p class="article-description">{{ item.Description }}</p>
                    <div class="article-meta">
                        <span class="article-category">分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
                        <span class="article-date">发布于：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                        <span class="article-views">浏览量：{{ item.Views }}</span>
                    </div>
                </div>
            </a>
        </li>
    {% empty %}
        <li class="no-content">
            目前还没有任何文章发布，敬请期待！
        </li>
    {% endfor %}
{% endarchiveList %}

{# 分页导航区域 #}
<div class="pagination-nav">
    {% pagination pages with show="5" %}
        <ul>
            <li class="page-item {% if pages.FirstPage.IsCurrent