怎样在`archiveList`中实现带分页功能的文档列表展示？

当我们管理网站内容时，经常会遇到这样的情况：某个分类下的文章、产品或新闻数量众多，如果把所有内容都堆砌在一个页面上，不仅会造成页面加载缓慢，影响用户体验，更会让访问者在海量信息中难以找到所需。这时候，引入分页功能就显得尤为重要了。分页能够将大量内容拆分成若干个小页面，让用户可以逐页浏览，极大地提升了网站的可用性和访问效率。

在 AnQiCMS 中，实现带分页功能的文档列表展示非常直观和灵活，主要得益于其强大的模板标签系统。我们主要会用到两个核心标签：archiveList 和 pagination。

核心要素：构建带分页的文档列表

要在一个页面上展示带分页的文档列表，我们首先需要从数据库中获取文档数据，然后在此基础上添加分页导航。

archiveList 标签：数据的源头

archiveList 标签是 AnQiCMS 中用于获取文档列表的核心标签。它非常灵活，可以通过多种参数来筛选和排序您想要展示的文档。对于分页列表，最关键的一点是，您需要明确告诉 archiveList 它将用于生成分页列表。

关键参数：type="page"

当您在 archiveList 标签中设置 type="page" 时，AnQiCMS 就会知道这个列表需要进行分页处理。它不仅会返回当前页的文档数据，还会将完整的页面数据（如总页数、当前页码、首页链接、末页链接等）传递给后续的分页标签使用。

其他常用参数：

• moduleId：指定要获取哪个内容模型（如文章、产品）的文档。例如 moduleId="1" 代表文章模型。
• categoryId：指定要获取某个分类下的文档。您可以传入单个分类ID，也可以用逗号分隔多个ID，例如 categoryId="1,2,3"。如果您不指定，AnQiCMS 会尝试读取当前页面的分类ID。如果您不希望它自动读取，可以明确设置为 categoryId="0"。
• limit：控制每页显示的文档数量，例如 limit="10" 表示每页显示 10 条文档。
• order：定义文档的排序方式，常见的有 id desc (按ID倒序，即最新发布)、views desc (按浏览量倒序，即热门文档)。
• q：用于搜索功能，当用户通过搜索框提交关键词时，此参数可以捕获并用于筛选标题中包含该关键词的文档。

pagination 标签：分页的舵手

pagination 标签与 archiveList 标签紧密协作，负责生成页面底部的分页导航链接。它会接收 archiveList 传递过来的分页信息，并将其渲染成用户可以点击的上一页、下一页、页码列表等。

关键参数：show

show 参数控制着分页导航中同时显示多少个页码链接。例如，show="5" 表示最多显示当前页左右各 2 个页码，加上当前页总共 5 个。

可用信息：

pagination 标签提供了一系列非常方便的变量，让您可以灵活构建分页导航：

• pages.TotalItems：总文档数量。
• pages.TotalPages：总页数。
• pages.CurrentPage：当前页码。
• pages.FirstPage：首页对象，包含 Name (如 “首页”) 和 Link (首页URL) 以及 IsCurrent 属性。
• pages.PrevPage：上一页对象，同样包含 Name 和 Link。
• pages.Pages：一个数组，包含了中间部分的页码对象，每个对象有 Name、Link 和 IsCurrent 属性。
• pages.NextPage：下一页对象。
• pages.LastPage：末页对象。

利用这些信息，您可以轻松构建出符合您网站设计风格的分页导航。

实际操作：将它们组合起来

现在，让我们通过一个实际的代码示例，看看如何在 AnQiCMS 模板中实现带分页功能的文档列表。假设我们想在一个列表页显示某个分类下的文章，每页 10 篇，并添加分页导航。

<div class="document-list-container">
    <ul class="document-list">
        {% archiveList archives with type="page" categoryId="1" limit="10" order="id desc" %}
            {% for item in archives %}
            <li class="document-item">
                <a href="{{item.Link}}" class="item-link">
                    <h3>{{item.Title}}</h3>
                    <p>{{item.Description}}</p>
                    <div class="item-meta">
                        <span class="category-name">分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
                        <span class="publish-date">发布时间：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
                        <span class="views">浏览量：{{item.Views}}</span>
                    </div>
                </a>
                {% if item.Thumb %}
                <div class="item-thumb">
                    <img src="{{item.Thumb}}" alt="{{item.Title}}">
                </div>
                {% endif %}
            </li>
            {% empty %}
            <li class="no-content">
                抱歉，当前分类下没有任何文档。
            </li>
            {% endfor %}
        {% endarchiveList %}
    </ul>

    <div class="pagination-container">
        {% pagination pages with show="5" %}
            <ul class="pagination-nav">
                {# 首页链接 #}
                <li class="page-item {% if pages.FirstPage.IsCurrent %}active{% endif %}">
                    <a href="{{pages.FirstPage.Link}}">{{pages.FirstPage.Name}}</a>
                </li>
                {# 上一页链接 #}
                {% if pages.PrevPage %}
                <li class="page-item">
                    <a href="{{pages.PrevPage.Link}}">{{pages.PrevPage.Name}}</a>
                </li>
                {% endif %}
                {# 中间页码列表 #}
                {% for item in pages.Pages %}
                <li class="page-item {% if item.IsCurrent %}active{% endif %}">
                    <a href="{{item.Link}}">{{item.Name}}</a>
                </li>
                {% endfor %}
                {# 下一页链接 #}
                {% if pages.NextPage %}
                <li class="page-item">
                    <a href="{{pages.NextPage.Link}}">{{pages.NextPage.Name}}</a>
                </li>
                {% endif %}
                {# 末页链接 #}
                <li class="page-item {% if pages.LastPage.IsCurrent %}active{% endif %}">
                    <a href="{{pages.LastPage.Link}}">{{pages.LastPage.Name}}</a>
                </li>
            </ul>
            <p class="pagination-info">
                总计 {{pages.TotalItems}} 篇文章，共 {{pages.TotalPages}} 页，当前第 {{pages.CurrentPage}} 页。
            </p>
        {% endpagination %}
    </div>
</div>

代码解析：

1. archiveList 部分：

   • 我们定义了一个变量 archives 来存储获取到的文档列表。
   • type="page" 明确启用了分页模式。
   • categoryId="1" 指定获取 ID 为 1 的分类下的文档，您可以根据实际需求替换为您的分类 ID。
   • limit="10" 设置每页显示 10 篇文章。
   • order="id desc" 按照文档 ID 降序排列，通常意味着最新的文章在前。
   • {% for item in archives %} 循环遍历当前页的每一篇文档，item 变量包含了文档的各项属性，如 Title、Link、Description 等。
   • {% categoryDetail with name="Title" id=item.CategoryId %} 用于在文档列表中显示其所属分类的名称。
   • {{stampToDate(item.CreatedTime, "2006-01-02")}} 将文档的创建时间戳格式化为 YYYY-MM-DD 形式。
   • {% empty %} 块在没有文档时显示提示信息，提升用户体验。

2. pagination 部分：

   • 我们定义了一个变量 pages 来接收 archiveList 传递的分页数据。
   • show="5" 表示分页导航中最多同时显示 5 个页码链接（例如：1 2 [3] 4