`archiveList`标签如何控制文档列表的显示数量、排序方式和分页逻辑？

在安企CMS中，archiveList标签无疑是内容展示的核心利器，它为网站的内容列表提供了极大的灵活性和控制力。无论是想在首页展示最新文章，还是在分类页实现复杂的筛选分页，archiveList都能通过其丰富的参数配置，帮助我们精准地呈现内容。接下来，我们就一起深入探讨如何利用这个标签来控制文档列表的显示数量、排序方式以及实现精妙的分页逻辑。

掌控文档显示数量：limit参数的灵活运用

在构建网站页面时，我们经常需要控制内容列表的长度。例如，在网站首页，可能只希望展示最新的5篇文章；在侧边栏，也许只想显示热门的10个产品。archiveList标签通过limit参数，赋予了我们精准控制显示数量的能力。

最常见的用法是直接指定一个数字，表示要获取的文档条数。比如，如果你想在某个位置显示最近的8篇文章：

{% archiveList latestArticles with type="list" limit="8" %}
    {% for item in latestArticles %}
        <li><a href="{{ item.Link }}">{{ item.Title }}</a></li>
    {% empty %}
        <li>暂无文章可显示。</li>
    {% endfor %}
{% endarchiveList %}

这里，limit="8"就确保了列表最多只显示8篇文章。

limit参数还支持一种更高级的“偏移”模式，即从结果集的某个位置开始，再获取指定数量的文档。这对于需要跳过前面几条内容（比如头条推荐之后显示普通列表）的场景非常有用。它的格式是"起始偏移量,获取数量"。例如，如果想跳过前2篇文章，从第3篇开始显示5篇文章：

{% archiveList featuredArticles with type="list" limit="2,5" %}
    {% for item in featuredArticles %}
        <li><a href="{{ item.Link }}">{{ item.Title }}</a> - 从第三篇开始的第{{ forloop.Counter }}篇</li>
    {% empty %}
        <li>暂无文章可显示。</li>
    {% endfor %}
{% endarchiveList %}

这样的配置让内容展示更加精细化，能够满足各种布局需求。

定制内容排序方式：order参数的策略选择

内容的呈现顺序对用户体验和信息传达至关重要。archiveList标签通过order参数，让你能够灵活地定义文档的排序方式，以突出最重要的信息。

order参数接受一个字符串，包含排序的字段和排序方向（asc为升序，desc为降序）。常用的排序字段包括：

• id desc：按照文档的ID降序排列，这通常意味着按发布时间从最新到最旧显示。
• views desc：按照文档的浏览量降序排列，这能帮助我们展示最受欢迎或最热门的内容。
• sort desc：按照后台自定义的排序字段降序排列。如果后台为文档设置了手动排序权重，这个选项会非常实用。

举个例子，如果你想在侧边栏展示5篇阅读量最高的文章：

<div class="sidebar-hot-articles">
    <h3>热门文章</h3>
    <ul>
    {% archiveList hotArticles with type="list" order="views desc" limit="5" %}
        {% for item in hotArticles %}
            <li><a href="{{ item.Link }}">{{ item.Title }} <small>({{ item.Views }} 阅读)</small></a></li>
        {% empty %}
            <li>暂无热门文章。</li>
        {% endfor %}
    {% endarchiveList %}
    </ul>
</div>

而如果想在分类页显示最新的内容，则可以这样使用：

<div class="category-new-list">
    <h2>最新发布</h2>
    <ul>
    {% archiveList newArrivals with type="list" order="id desc" limit="10" %}
        {% for item in newArrivals %}
            <li><a href="{{ item.Link }}">{{ item.Title }}</a> - 发布于 {{ stampToDate(item.CreatedTime, "2006-01-02") }}</li>
        {% empty %}
            <li>此分类暂无最新文章。</li>
        {% endfor %}
    {% endarchiveList %}
    </ul>
</div>

通过巧妙地搭配order参数，我们能让网站的内容始终以最合理、最吸引人的方式呈现在用户面前。

实现内容分页逻辑：type="page"与pagination标签的联动

当网站内容量庞大时，分页功能是必不可少的，它能有效提升页面的加载速度和用户浏览体验。在安企CMS中，实现分页需要archiveList标签与pagination标签的巧妙配合。

首先，在archiveList标签中，我们需要将type参数设置为"page"。这将告诉系统，我们希望获取一个可分页的文档列表，而不是一个固定长度的列表。此时，limit参数将用于定义每页显示的文档数量。

例如，要在文章列表页每页显示10篇文章：

{% archiveList articles with type="page" limit="10" %}
    <div class="article-list">
        {% for item in articles %}
            <article>
                <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
                <p>{{ item.Description }}</p>
                <span>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
            </article>
        {% empty %}
            <p>此列表暂无内容。</p>
        {% endfor %}
    </div>
{% endarchiveList %}

仅仅这样设置，页面并不会自动出现页码导航。此时，就需要pagination标签登场了。pagination标签会读取archiveList准备好的分页数据，并生成实际的页码导航链接。它通常被放在archiveList标签的下方，并且包裹在一个{% pagination pages with show="5" %}...{% endpagination %}结构中。其中，show="5"表示最多显示5个页码按钮（如1, 2, 3, 4, 5）。

一个完整的分页列表及其页码导航的示例如下：

{# 假设这是文章列表页模板 #}
<div class="main-content">
    {% archiveList articles with type="page" limit="10" order="id desc" %}
        <div class="article-list">
            {% for item in articles %}
                <article>
                    <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
                    <p>{{ item.Description }}</p>
                    <span>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                </article>
            {% empty %}
                <p>此列表暂无内容。</p>
            {% endfor %}
        </div>

        {# 分页导航区域 #}
        <div class="pagination-nav">
            {% pagination pages with show="5" %}
                <ul>
                    {# 首页按钮 #}
                    <li {% if pages.FirstPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.FirstPage.Link }}">{{ pages.FirstPage.Name }}</a></li>
                    
                    {# 上一页按钮 #}
                    {% if pages.PrevPage %}
                        <li><a href="{{ pages.PrevPage.Link }}">{{ pages.PrevPage.Name }}</a></li>
                    {% endif %}

                    {# 中间页码按钮组 #}
                    {% for pageItem in pages.Pages %}
                        <li {% if pageItem.IsCurrent %}class="active"{% endif %}><a href="{{ pageItem.Link }}">{{ pageItem.Name }}</a></li>
                    {% endfor %}

                    {# 下一页按钮 #}
                    {% if pages.NextPage %}
                        <li><a href="{{ pages.NextPage.Link }}">{{ pages.NextPage.Name }}</a></li>
                    {% endif %}
                    
                    {# 尾页按钮 #}
                    <li {% if pages.LastPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.LastPage.Link }}">{{ pages.LastPage.Name }}</a></li>
                    
                    <li class="info">总数：{{ pages.TotalItems }}条，共：{{ pages.TotalPages }}页，当前第{{ pages.CurrentPage }}页</li>
                </ul>
            {% endpagination %}
        </div>
    {% endarchiveList %}
</div>

在这个例子中，pages变量包含了所有与分页相关的信息，例如当前页码（pages.CurrentPage）、总页数（pages.TotalPages）、上一页链接（pages.PrevPage.Link）以及一系列中间页码按钮（pages.Pages）。通过遍历pages.Pages，我们就能生成一个完整的页码导航条。

值得一提的是，当type="page"启用时，archiveList还会自动识别URL中的q参数