如何在安企CMS模板中列出某个特定标签下的所有文档，并支持分页？

在内容管理系统中，有效地组织和展示文章是提升用户体验的关键。当内容通过标签进行细致分类时，我们常常需要在一个页面上列出某个特定标签下的所有文章，并且为了保持页面的整洁和加载速度，分页功能也变得不可或缺。安企CMS提供了强大且灵活的模板标签，让这一需求能够轻松实现。

本篇文章将详细介绍如何在安企CMS模板中，结合 tagDataList 标签和 pagination 标签，优雅地列出特定标签下的所有文档，并支持完善的分页功能。

认识核心工具：tagDataList 和 pagination 标签

要实现在特定标签下文档的列表与分页，我们主要会用到两个强大的模板标签：tagDataList 和 pagination。

  1. tagDataList 标签： 这个标签专门用于获取与特定标签关联的文档列表。它非常灵活，可以通过多种参数来筛选和控制所获取的文档。对于分页需求，一个关键的参数是 type="page"，它会告诉系统为这个列表准备分页数据。

    常用参数速览：

    • tagId：指定要获取哪个标签下的文档。通常在标签详情页，系统会自动识别当前标签的ID；在其他页面，你可以手动指定一个标签ID。
    • moduleId：如果你的网站有文章和产品等不同的内容模型，可以通过这个参数指定获取哪个模型下的文档，例如 moduleId="1"（假设文章模型的ID是1）。
    • limit：设定每页显示多少条文档。
    • order：定义文档的排序方式，比如 order="id desc"（按ID倒序，即最新发布）、order="views desc"（按浏览量倒序）。
    • type="page"：这是实现分页的关键！它会使 tagDataList 返回一个可分页的数据集，供 pagination 标签使用。

    tagDataList 获取到的文档数据会是一个数组对象，通常我们将其命名为 archives（或其他你喜欢的名称）。数组中的每个 item 都包含了文档的详细信息，例如 item.Id、item.Title、item.Link、item.Description、item.Thumb（缩略图）、item.Views（浏览量）和 item.CreatedTime（发布时间）等。

  2. pagination 标签： 这个标签负责生成分页导航链接。它需要接收 tagDataList 准备好的分页数据。通过 pagination，你可以轻松生成“首页”、“上一页”、“下一页”、“尾页”以及一系列页码链接。

    常用参数速览：

    • show：控制分页导航中最多显示多少个页码链接，例如 show="5" 会显示当前页附近最多5个页码。

    pagination 标签会提供一个包含分页信息的对象，通常我们将其命名为 pages。这个对象里包含了诸如 pages.TotalItems（总文档数）、pages.TotalPages（总页数）、pages.CurrentPage（当前页码）以及指向各个分页链接的对象（pages.FirstPage、pages.PrevPage、pages.NextPage、pages.LastPage 和 pages.Pages）。

实践操作：构建特定标签文档列表与分页

假设我们正在构建一个标签详情页，希望展示该标签下的所有文章，并支持分页。

第一步：获取当前标签信息（可选但推荐） 在页面顶部，我们可能希望显示当前标签的名称和描述。这可以通过 tagDetail 标签来实现。

{# 假设这是 tag/list.html 或 tag/detail.html 模板 #}
{% tagDetail tagInfo with name="Title" %}
<h1>{{ tagInfo }}</h1>
{% tagDetail tagDescription with name="Description" %}
<p>{{ tagDescription }}</p>

第二步：使用 tagDataList 获取分页文档数据 接下来，我们将使用 tagDataList 标签来获取这个标签下的文档列表。关键在于设置 type="page" 和 limit 参数，这将为分页做好准备。

{# 使用 tagDataList 获取文档列表，并将 type 设置为 "page" 以支持分页 #}
{% tagDataList archives with type="page" limit="10" %}
    <ul class="document-list">
        {% for item in archives %}
        <li>
            <a href="{{ item.Link }}">
                <h3>{{ item.Title }}</h3>
                {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}">
                {% endif %}
                <p>{{ item.Description }}</p>
                <div class="meta">
                    <span>发布日期: {{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                    <span>浏览量: {{ item.Views }}</span>
                </div>
            </a>
        </li>
        {% empty %}
        <p>该标签下暂时没有找到任何文档。</p>
        {% endfor %}
    </ul>
{% endtagDataList %}

这里我们迭代了 archives 变量中的每个文档 item，并展示了标题、缩略图、简介、发布日期和浏览量等信息。{% empty %} 标签用于在列表为空时显示友好提示。

第三步：使用 pagination 构建分页导航 现在，文档列表已经准备好了，我们需要添加分页导航。pagination 标签需要放在 tagDataList 标签之后，以便它能够访问到 tagDataList 生成的 pages 对象。

{# 分页导航区域，假设 pages 变量由上面的 tagDataList 标签自动填充 #}
<div class="pagination-nav">
    {% pagination pages with show="5" %}
    <ul class="page-links">
        {# 首页链接 #}
        <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 pageItem in pages.Pages %}
        <li class="page-item {% if pageItem.IsCurrent %}active{% endif %}">
            <a href="{{ pageItem.Link }}">{{ pageItem.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>
    <div class="page-info">
        共 {{ pages.TotalItems }} 篇文章，{{ pages.TotalPages }} 页，当前第 {{ pages.CurrentPage }} 页。
    </div>
    {% endpagination %}
</div>

这里，我们利用 pages 对象的各个属性来构建完整的分页导航。pageItem.IsCurrent 可以用来给当前页码添加高亮样式，pages.PrevPage 和 pages.NextPage 的条件判断则确保了只有在有上一页/下一页时才显示相应的链接。

完整示例代码

将上述代码片段整合在一起，一个包含特定标签文档列表和分页功能的页面就完成了：

”`twig {% extends ‘base.html’ %} {# 继承基础模板，确保头部、尾部等公共元素存在 #}

{% block content %} {# 在内容区域定义 #}

{# 第一部分：显示当前标签的名称和描述 #} 

{% tagDetail tagInfo with name="Title" %}