如何获取并显示特定Tag标签下的所有文档列表？
作为一名深谙AnQiCMS运作的网站运营人员，我非常理解高效内容管理和优化的重要性。标签（Tag）是组织内容、提升用户体验和SEO表现的关键要素之一。通过标签，我们不仅能够为读者提供更精准的内容聚合，还能帮助搜索引擎更好地理解网站内容结构。现在，我将详细阐述在AnQiCMS中如何获取并展示特定Tag标签下的所有文档列表。
Tag标签在AnQiCMS中的作用与显示需求
在AnQiCMS中，Tag标签是一种灵活的内容分类方式，它超越了传统分类的层级限制，允许内容以更具关联性和主题化的方式被串联起来。例如，一篇关于“AnQiCMS模板制作”的文章，除了可以归属于“技术教程”分类外，还可以被打上“模板”、“前端”、“Go语言”等多个标签。这极大地丰富了内容间的关系网，方便用户根据兴趣点探索更多相关内容。
当我们需要展示特定Tag标签下的所有文档时，通常会在“标签详情页”（例如 tag/list.html）或网站的其他模块（如侧边栏的热门标签文章、页面底部的相关标签文章）进行。AnQiCMS提供了专门的模板标签来满足这一需求，其核心是 tagDataList 标签。
运用tagDataList标签获取文档列表
在AnQiCMS的模板系统中，tagDataList 是用于获取与指定Tag相关联的文档列表的关键标签。它的设计旨在简洁高效地实现这一功能。
要使用 tagDataList，我们需要将其包裹在一个 for 循环中，因为该标签返回的是一个文档（archive）对象的数组。基本的用法如下：
{% tagDataList archives with tagId="1" type="page" limit="10" %}
{# 循环遍历文档列表 #}
{% for item in archives %}
{# 文档信息的显示代码 #}
{% endfor %}
{% endtagDataList %}
在 tagDataList 标签中，有一些重要的参数可以帮助我们精确控制获取到的文档列表：
tagId: 这是指定目标Tag标签的唯一标识符。如果您正在一个Tag详情页（如tag/list.html）中，系统通常会自动识别当前页面的tagId，此时您可以省略这个参数。如果您想在其他页面手动指定一个Tag的文档列表，就需要明确地设置tagId="X"（其中X是Tag的ID）。moduleId: 如果您的网站有多种内容模型（如文章、产品），并且您只想获取特定模型下的Tag文档，可以通过设置moduleId="Y"来筛选（例如，moduleId="1"可能代表文章模型）。order: 这个参数用于控制文档的排序方式。常见的选项有id desc（按最新发布倒序）、views desc（按浏览量倒序）、sort desc（按后台自定义排序）。limit: 决定了列表显示的最大文档数量。如果您希望分页显示，可以设置一个每页显示的文档数，例如limit="10"。如果是非分页列表，也可以使用offset模式，如limit="2,10"表示从第2条开始获取10条数据。type: 这个参数非常关键，它决定了tagDataList的返回类型。当设置为type="page"时，它会返回一个支持分页的对象，后续可以配合pagination标签实现分页功能。如果设置为type="list"，则只返回指定limit数量的文档，不提供分页信息。siteId: 如果您在使用AnQiCMS的多站点管理功能，并且需要获取其他站点下的Tag文档，可以指定siteId="Z"来实现。
tagDataList 标签返回的 archives 变量是一个数组，其中每个 item 都代表一个文档，包含了丰富的字段信息，例如：Id（文档ID）、Title（文档标题）、Link（文档链接）、Description（文档描述）、Thumb（缩略图）、CreatedTime（创建时间，需用 stampToDate 格式化）、Views（浏览量）等等。
实际模板代码示例
假设我们正在编辑 tag/list.html 模板，希望显示当前标签的名称，以及该标签下的所有文章，并提供分页功能。
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<title>{% tdk with name="Title" siteName=true %}</title>
<meta name="keywords" content="{% tdk with name="Keywords" %}">
<meta name="description" content="{% tdk with name="Description" %}">
<link rel="stylesheet" href="{% system with name="TemplateUrl" %}/css/style.css">
</head>
<body>
{# 导航栏或其他页面头部 #}
{% include "partial/header.html" %}
<div class="main-content">
<div class="container">
{# 获取当前标签的详细信息，例如标签名称 #}
{% tagDetail currentTag with name="Title" %}
<h1>标签：{{ currentTag }} 下的文档</h1>
<div class="tag-documents-list">
{% tagDataList archives with type="page" limit="10" %}
{% for item in archives %}
<div class="document-item">
<a href="{{item.Link}}" class="document-link">
<h2>{{item.Title}}</h2>
{% if item.Thumb %}
<img src="{{item.Thumb}}" alt="{{item.Title}}" class="document-thumbnail">
{% endif %}
<p class="document-description">{{item.Description}}</p>
</a>
<div class="document-meta">
<span>发布于：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
<span>浏览：{{item.Views}}次</span>
{# 获取文档所属分类的名称 #}
<span>分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
</div>
</div>
{% empty %}
<p class="no-documents">当前标签下暂无任何文档。</p>
{% endfor %}
{# 列表分页代码 #}
{% pagination pages with show="5" %}
<nav aria-label="Page navigation" class="pagination-wrapper">
<ul class="pagination">
{% if pages.FirstPage %}
<li class="page-item {% if pages.FirstPage.IsCurrent %}active{% endif %}">
<a class="page-link" href="{{pages.FirstPage.Link}}">{{pages.FirstPage.Name}}</a>
</li>
{% endif %}
{% if pages.PrevPage %}
<li class="page-item">
<a class="page-link" href="{{pages.PrevPage.Link}}">{{pages.PrevPage.Name}}</a>
</li>
{% endif %}
{% for p in pages.Pages %}
<li class="page-item {% if p.IsCurrent %}active{% endif %}">
<a class="page-link" href="{{p.Link}}">{{p.Name}}</a>
</li>
{% endfor %}
{% if pages.NextPage %}
<li class="page-item">
<a class="page-link" href="{{pages.NextPage.Link}}">{{pages.NextPage.Name}}</a>
</li>
{% endif %}
{% if pages.LastPage %}
<li class="page-item {% if pages.LastPage.IsCurrent %}active{% endif %}">
<a class="page-link" href="{{pages.LastPage.Link}}">{{pages.LastPage.Name}}</a>
</li>
{% endif %}
</ul>
</nav>
{% endpagination %}
{% endtagDataList %}
</div>
</div>
</div>
{# 页脚或其他页面底部 #}
{% include "partial/footer.html" %}
</body>
</html>
在这段代码中，我们首先使用 tagDetail 获取当前Tag的标题，作为页面的主标题。接着，tagDataList 以 type="page" 的方式获取了文档列表，并设置每页显示10篇文档。在 for 循环内部，我们展示了文档的标题、链接、缩略图、描述、发布时间、浏览量以及所属分类。最后，通过 pagination 标签生成了完整的分页导航。
进阶用法与注意事项
在实际应用中，您可能会有更复杂的需求。例如，在网站的首页或文章详情页侧边栏，显示某个特定热门Tag下的几篇最新文档。这时，您可以直接指定 tagId 和 limit，并将 type 设置为 list：
{# 在首页或侧边栏显示Tag ID为5的最新5篇文档 #}
<h3>热门标签文章</h3>
<ul>
{% tagDataList hotArticles with tagId="5" type="list" limit="5" order="id desc" %}
{% for item in hotArticles %}
<li><a href="{{item.Link}}">{{item.Title}}</a></li>
{% empty %}
<li>暂无热门标签文章。</li>
{% endfor %}
{% endtagDataList %}
</ul>
请记住，AnQiCMS的模板标签是区分大小写的，务必按照文档中提供的字段名和参数名准确书写。通过灵活运用 tagDataList 及其他辅助标签，您可以构建出高度定制化且内容丰富、易于导航的网站页面。
总结
AnQiCMS的 tagDataList 标签为网站运营人员提供了获取和展示特定Tag标签下文档列表的强大而灵活的工具。无论是构建专门的标签归档页面，还是在网站其他区域展示相关内容，该标签都能通过简单的参数配置，满足多样化的内容聚合需求。结合分页功能，它还能有效提升用户体验，确保即使是