如何获取并显示指定Tag下的文档列表，并支持分页功能？

在网站内容管理中，将文档按照其所属的标签（Tag）进行归类和展示，是提升用户体验和内容可发现性的重要策略。AnQiCMS 提供了一套直观而强大的模板标签，帮助我们轻松实现这一目标，同时还能灵活地支持分页功能，即使面对海量内容也能保持页面的整洁和加载速度。

要获取并显示指定标签下的文档列表，并实现分页，我们需要用到 AnQiCMS 模板引擎中的两个核心标签：tagDataList 和 pagination。这两个标签协同工作，能够帮助我们构建出功能完善的标签文档列表页面。

核心标签：Tag文档列表标签 tagDataList

tagDataList 标签是专门用于从数据库中检索与特定标签关联的文档列表。它的使用方式非常灵活，可以根据我们的需求进行定制。

在使用时，我们通常会以这样的形式来定义它：{% tagDataList archives with tagId="1" type="page" limit="10" %}。这里，archives 是我们为文档列表定义的变量名，你可以根据自己的习惯来命名。

以下是一些关键参数的说明：

• tagId：这是最核心的参数，用于指定我们想要获取哪个标签下的文档。你可以直接填写标签的 ID（例如 tagId="1"），也可以让系统自动识别当前页面的标签 ID。如果当前页面本身就是某个标签的详情页（例如 tag/list.html 或 tag/index.html），tagDataList 标签通常会自动获取该标签的 ID，我们便无需手动指定。
• type="page"：这个参数至关重要，它告诉系统我们需要一个支持分页的文档列表。只有设置了 type="page"，tagDataList 才会将列表数据和分页信息一起返回，以便后续结合 pagination 标签使用。
• limit：用于控制每页显示多少篇文档。例如，limit="10" 意味着每页显示 10 篇文档。
• moduleId：如果你需要筛选特定内容模型（如“文章”或“产品”）下的标签文档，可以通过此参数指定模型的 ID。例如，moduleId="1" 通常代表文章模型。
• order：定义文档的排序方式，常见的有 id desc（按ID降序，即最新发布）、views desc（按浏览量降序）等。

tagDataList 标签执行后，它会将符合条件的文档数据填充到我们定义的变量（例如 archives）中，这个变量是一个数组对象，我们可以通过 for 循环来遍历并显示每一篇文档的内容。

结合分页标签 pagination

当我们使用 tagDataList 并将 type 参数设置为 page 后，系统会生成相应的分页数据。这些分页数据可以通过 pagination 标签来渲染成用户可见的分页导航。

pagination 标签的使用方式如下：{% pagination pages with show="5" %}。其中，pages 是系统自动生成的包含分页信息的变量名。

• show：这个参数控制分页导航中一次性显示多少个页码。例如，show="5" 会显示当前页码前后共 5 个页码链接。

pagination 标签内部也需要通过 for 循环来遍历每一个页码链接，并显示“首页”、“上一页”、“下一页”和“尾页”等导航元素。它会根据当前页码和总页数，智能地生成完整的页码导航。

实战演练：获取并显示指定标签文档列表（含分页）

下面是一个完整的模板代码示例，展示了如何在 AnQiCMS 中获取某个标签下的文档列表并实现分页功能。假设这是一个标签详情页面的模板。

{# 假设我们正在一个标签详情页面，tagDataList 会自动获取当前标签ID #}

<div class="tag-documents">
    {# 获取当前标签的详细信息，例如标签名称和描述 #}
    {% tagDetail currentTag with name="Title" %}
    {% tagDetail tagDescription with name="Description" %}
    <h1>标签：{{ currentTag }}</h1>
    {% if tagDescription %}
        <p class="tag-description">{{ tagDescription }}</p>
    {% endif %}

    <ul class="document-list">
        {# 使用 tagDataList 标签获取当前标签下的文档列表，并开启分页功能 #}
        {% tagDataList archives with type="page" limit="10" order="id desc" %}
            {% for item in archives %}
            <li class="document-item">
                <a href="{{ item.Link }}" class="document-title">
                    <h3>{{ item.Title }}</h3>
                </a>
                {% if item.Thumb %}
                <div class="document-thumb">
                    <a href="{{ item.Link }}">
                        <img src="{{ item.Thumb }}" alt="{{ item.Title }}">
                    </a>
                </div>
                {% endif %}
                <p class="document-description">{{ item.Description }}</p>
                <div class="document-meta">
                    {# 获取文档所属分类的名称和链接 #}
                    <span>分类：<a href="{% categoryDetail with name='Link' id=item.CategoryId %}">{% categoryDetail with name='Title' id=item.CategoryId %}</a></span>
                    {# 格式化文档发布时间 #}
                    <span>发布时间：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                    <span>阅读量：{{ item.Views }}</span>
                </div>
            </li>
            {% empty %}
            {# 如果当前标签下没有文档，显示此内容 #}
            <li class="no-content">
                该标签下暂时没有相关文档。
            </li>
            {% endfor %}
        {% endtagDataList %}
    </ul>

    {# 渲染分页导航 #}
    <nav class="pagination-nav">
        {% pagination pages with show="5" %}
        <ul class="pagination-list">
            {# 首页链接 #}
            <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="pagination-info">
            总计 {{ pages.TotalItems }} 篇文档，共 {{ pages.TotalPages }} 页，当前第 {{ pages.CurrentPage }} 页。
        </div>
        {% endpagination %}
    </nav>
</div>

在这个示例中，我们首先通过 tagDetail 标签获取了当前标签的名称和描述，作为页面的标题和简介。接着，利用 tagDataList 标签，以 type="page" 的形式获取了每页 10 篇文档，并按 ID 降序排列。在遍历 archives 变量时，我们展示了文档的标题、缩略图、描述、所属分类、发布时间和阅读量。最后，通过 pagination 标签，配合 show="5" 参数，生成了完整的页码导航。

深入理解：如何获取Tag ID？

如前所述，在标签详情页面，tagDataList 会自动识别当前页面的 tagId。但如果需要在其他非标签详情页（例如首页或分类列表页）显示特定标签的文档列表，我们就需要手动指定 tagId。

手动获取 tagId 的方法有几种：

1. 从后台查看：登录 AnQiCMS 后台，进入 “内容管理” -> “文档标签” 页面，每个标签都会有一个唯一的 ID，可以直接复制使用。
2. 使用 tagDetail 标签：如果你知道标签的名称或别名，可以在模板中先通过 tagDetail 标签获取其 ID。例如： “`twig {% tagDetail specificTag with name=“Id” token=“anqicms” %} {# 假设标签别名为