在内容管理系统中，如何高效地展示大量文章或产品，同时又不牺牲用户体验，这通常是网站运营者需要面对的一个挑战。安企CMS（AnQiCMS）提供了强大的模板标签功能，其中pagination标签便是解决这一问题的利器，它能灵活地处理文章列表和产品列表的分页显示逻辑，让您的网站内容井然有序。

理解分页的重要性

想象一下，如果您的网站有成百上千篇新闻文章或商品，一次性全部加载显示在页面上，不仅会让页面变得臃肿、加载速度缓慢，更会让用户在浩如烟海的信息中迷失方向。分页机制应运而生，它将长列表内容切割成若干个小块，分批次展示，极大地提升了页面加载速度和用户浏览体验。同时，合理的分页也有助于搜索引擎更好地抓取和索引网站内容，对SEO表现同样至关重要。

pagination 标签概览

在安企CMS中，pagination标签是专门用来生成分页导航的。它能够接收由内容列表标签（如文章列表archiveList或产品列表）处理后的分页数据，并将其转化为用户友好的分页链接组。

这个标签的基本结构是这样的：

{% pagination pages with show="5" %}
    {# 在这里放置你的分页HTML结构 #}
{% endpagination %}

这里，pages是一个包含所有分页信息的变量，而show="5"则是一个可选参数，它告诉系统在分页导航中最多显示5个页码数字。

如何与内容列表协同工作？

pagination标签并非孤立存在，它需要与能够生成分页数据的列表标签配合使用。最常见的例子就是archiveList标签，它用于获取文章或产品列表。

当您希望archiveList标签生成的数据能够进行分页时，需要为其设置type="page"参数。例如，获取每页显示10篇文章的文章列表时，您的archiveList标签会是这样：

{% archiveList archives with type="page" limit="10" %}
    {# 循环显示文章内容 #}
{% endarchiveList %}

在这个例子中：

  • archives 是一个变量，包含了当前页面的文章数据。
  • type="page" 明确告诉系统，这个列表需要生成分页数据，而不仅仅是简单的内容罗列。
  • limit="10" 则定义了每页显示的文章数量。这个参数至关重要，它决定了总共有多少页，以及每页承载的内容量。

当archiveList（或其他支持分页的列表标签，如tagDataList、commentList）被设置为type="page"时，它会在后台准备好所有与分页相关的数据，并将这些数据传递给模板中的pages变量，供pagination标签使用。

pagination 标签的参数与内部变量解析

pagination标签内部能够访问一个名为pages的变量，这个变量包含了所有与分页状态相关的详细信息，您可以根据这些信息构建出各种样式的分页导航。

  1. show 参数

    • show="5"：控制分页导航中可见的页码数量。例如，当总页数很多时，show="5"会只显示当前页码周围的5个页码（如 ... 3 4 [5] 6 7 ...）。

  2. pages 变量的核心属性

    • pages.TotalItems：列表内容的总条目数。
    • pages.TotalPages：内容的总页数。
    • pages.CurrentPage：当前用户正在浏览的页码。

  3. 导航元素对象 pages变量还提供了几个便捷的对象，用于快速构建“首页”、“上一页”、“下一页”和“尾页”链接：

    • pages.FirstPage：包含Name（通常是“首页”）、Link（首页链接）和IsCurrent（是否当前页）属性。
    • pages.LastPage：包含Name（通常是“尾页”）、Link（尾页链接）和IsCurrent属性。
    • pages.PrevPage：包含Name（通常是“上一页”）、Link（上一页链接）属性。如果当前页是第一页，这个对象将不存在（为nil），您可以利用{% if pages.PrevPage %}进行判断。
    • pages.NextPage：包含Name（通常是“下一页”）、Link（下一页链接）属性。如果当前页是最后一页，这个对象将不存在。

  4. 中间页码数组 pages.Pages 这是一个数组，包含了所有需要显示的具体页码（根据show参数动态生成）。您需要使用{% for item in pages.Pages %}来遍历它。数组中的每个item都包含：

    • item.Name：页码数字。
    • item.Link：该页码的链接。
    • item.IsCurrent：一个布尔值，表示该页码是否为当前页。这对于给当前页码添加高亮样式非常有用。

实战演练：构建一个完整的分页导航

接下来，我们通过一个实际的代码示例，演示如何在安企CMS中实现文章列表的分页显示。

{# 1. 首先，使用 archiveList 标签获取需要分页的文章数据 #}
{% archiveList archives with type="page" limit="10" %}
    <div class="article-list">
        {% for item in archives %}
        <div class="article-item">
            <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
            <p>{{ item.Description }}</p>
            <span class="date">{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
        </div>
        {% empty %}
        <p>暂无文章内容。</p>
        {% endfor %}
    </div>
{% endarchiveList %}

{# 2. 接着，使用 pagination 标签生成分页导航 #}
<nav class="pagination-nav">
    {% pagination pages with show="5" %}
        <ul class="pagination-list">
            {# 显示总条数、总页数和当前页码，有助于用户了解整体进度 #}
            <li class="info">总计 {{pages.TotalItems}} 条，共 {{pages.TotalPages}} 页，当前第 {{pages.CurrentPage}} 页</li>

            {# 首页链接：如果当前页不是首页，则显示 #}
            {% if pages.FirstPage and not pages.FirstPage.IsCurrent %}
                <li><a href="{{pages.FirstPage.Link}}" class="page-link">{{pages.FirstPage.Name}}</a></li>
            {% endif %}

            {# 上一页链接：如果存在上一页，则显示 #}
            {% if pages.PrevPage %}
                <li><a href="{{pages.PrevPage.Link}}" class="page-link">{{pages.PrevPage.Name}}</a></li>
            {% endif %}

            {# 中间页码：循环显示根据 show 参数计算出的页码 #}
            {% for item in pages.Pages %}
                <li {% if item.IsCurrent %}class="active"{% endif %}>
                    <a href="{{item.Link}}" class="page-link">{{item.Name}}</a>
                </li>
            {% endfor %}

            {# 下一页链接：如果存在下一页，则显示 #}
            {% if pages.NextPage %}
                <li><a href="{{pages.NextPage.Link}}" class="page-link">{{pages.NextPage.Name}}</a></li>
            {% endif %}

            {# 尾页链接：如果当前页不是尾页，则显示 #}
            {% if pages.LastPage and not pages.LastPage.IsCurrent %}
                <li><a href="{{pages.LastPage.Link}}" class="page-link">{{pages.LastPage.Name}}</a></li>
            {% endif %}
        </ul>
    {% endpagination %}
</nav>

这段代码首先通过archiveList获取并展示了文章列表，然后紧接着使用pagination标签构建了分页导航。它根据pages变量提供的数据，动态判断并显示了“首页”、“上一页”、“具体页码”、“下一页”和“尾页”链接，并为当前页码添加了active类名以便于CSS高亮显示。

不止文章和产品：其他列表的分页应用

pagination标签的灵活性远不止于文章和产品。在安企CMS中，凡是支持type="page"参数的列表标签，都可以结合pagination标签来实现分页功能。例如：

  • 标签（Tag）下的文档列表： tagDataList标签同样支持type="page"，您可以在标签详情页展示该标签下所有文档的分页列表。
  • 评论列表： commentList标签也可以通过type="page"实现评论内容的分页展示。

这种统一的设计思想使得在安企CMS