作为一名资深安企CMS网站运营人员，我深知高质量的内容和便捷的用户体验是吸引并留住用户的关键。标签（Tag）作为内容组织的重要维度，不仅能帮助用户快速找到感兴趣的内容，也是内部链接优化和SEO策略不可或缺的一部分。在安企CMS中，tagDataList标签正是我们用于展示指定标签下文档的强大工具。
这篇文章将详细阐述如何在安企CMS模板中有效利用tagDataList标签来展示特定标签下的文档，从而优化您的网站内容呈现。
理解tagDataList标签及其作用
tagDataList标签的核心功能是根据指定的标签ID检索并列出所有与之关联的文档。这对于构建标签归档页、在文章详情页展示相关标签下的内容，或是任何需要按标签聚合文档的场景都非常有用。通过精确地调用此标签，您可以为用户提供更细致、更相关的内容导航体验。
tagDataList标签的基本用法
tagDataList标签的使用方式与其他列表标签类似，您需要定义一个变量来接收返回的文档列表，并在标签内通过循环遍历这些文档。最基本的用法是指定一个tagId来获取该标签下的所有文档：
{% tagDataList archives with tagId="1" %}
{% for item in archives %}
<div class="tag-document-item">
<a href="{{item.Link}}">{{item.Title}}</a>
<p>{{item.Description}}</p>
</div>
{% endfor %}
{% endtagDataList %}
在上述示例中，archives是接收文档列表的变量。tagId="1"表示我们希望获取ID为1的标签下的所有文档。如果您的模板当前正处于某个标签的详情页或列表页，并且您省略了tagId参数，tagDataList会自动识别并获取当前页面的标签ID下的文档。
tagDataList标签的常用参数
为了更精准地控制文档的显示，tagDataList标签提供了多个参数供我们调整：
tagId: 这是指定要显示哪个标签下文档的核心参数。您可以直接在后台管理界面找到标签的ID，然后将其赋值给此参数。如前所述，在标签相关的页面中，省略此参数将自动获取当前页面的标签ID。moduleId: 如果您的网站有多种内容模型（例如文章、产品），并且您只想展示特定模型下的标签文档，可以使用moduleId参数进行筛选。例如，moduleId="1"通常用于获取文章模型下的文档。order: 此参数用于指定文档的排序方式。常见的排序规则包括：order="id desc"：按文档ID倒序（最新发布）排列。order="views desc"：按浏览量倒序排列（热门文档）。order="sort desc"：按后台自定义排序倒序排列。
limit: 用于控制返回文档的数量。例如，limit="10"将只显示前10条文档。当您不需要分页，只想显示固定数量的“推荐”或“最新”文档时，此参数非常有用。它也支持“offset”模式，例如limit="2,10"将从第2条文档开始获取10条数据。type: 这个参数是控制列表行为的关键。type="list"：默认值，只显示limit参数指定数量的文档，不提供分页功能。type="page"：开启分页功能。当设置为type="page"时，通常会结合pagination标签一起使用，来生成完整的页码导航。
siteId: 如果您的安企CMS是多站点部署，并且您希望调用其他站点下的标签文档，可以通过指定siteId来实现。
循环遍历并显示文档数据
tagDataList返回的archives变量是一个文档对象的数组。在{% for item in archives %}循环中，item变量代表了当前循环的每一个文档。您可以访问item对象的各种属性来显示文档信息：
item.Id: 文档ID。item.Title: 文档标题。item.Link: 文档的访问链接。item.Description: 文档简介或描述。item.Thumb: 文档缩略图的URL。item.Logo: 文档封面首图的URL。item.CreatedTime: 文档创建时间（时间戳格式）。通常需要通过stampToDate过滤器进行格式化，例如{{stampToDate(item.CreatedTime, "2006-01-02")}}。item.Views: 文档浏览量。item.CategoryId: 文档所属分类ID。- 以及文档模型中设置的其他自定义字段。
结合分页标签实现完整的标签归档页
对于一个完整的标签归档页面，我们通常需要展示大量文档并提供分页功能，以便用户浏览。这时，我们需要将tagDataList的type参数设置为"page"，并结合pagination标签一起使用。
以下是一个完整的示例，展示了如何在标签归档页中使用tagDataList和pagination：
{# tag/list.html 或 tag/index.html 模板文件 #}
{# 页面标题和描述可以从当前Tag详情中获取 #}
<h1>{% tagDetail with name="Title" %}</h1>
<p>{% tagDetail with name="Description" %}</p>
<div class="tag-documents-list">
{# 使用 tagDataList 获取当前Tag下的文档，并开启分页功能，每页显示10条 #}
{% tagDataList archives with type="page" limit="10" %}
{% for item in archives %}
<div class="document-item">
{% if item.Thumb %}
<a href="{{item.Link}}" class="document-thumb">
<img alt="{{item.Title}}" src="{{item.Thumb}}">
</a>
{% endif %}
<div class="document-info">
<a href="{{item.Link}}" class="document-title">
<h3>{{item.Title}}</h3>
</a>
<p class="document-description">{{item.Description}}</p>
<div class="document-meta">
<span>发布于：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
<span>阅读量：{{item.Views}}</span>
{# 如果需要显示分类名称，可以嵌套 categoryDetail #}
<span>分类：<a href="{% categoryDetail with name='Link' id=item.CategoryId %}">{% categoryDetail with name='Title' id=item.CategoryId %}</a></span>
</div>
</div>
</div>
{% empty %}
<div class="no-content">
该标签下暂无任何文档内容。
</div>
{% endfor %}
{% endtagDataList %}
{# 分页导航区域 #}
<div class="pagination-area">
{% pagination pages with show="5" %}
<nav>
<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>
</nav>
<div class="pagination-summary">
共 {{pages.TotalItems}} 条文档，{{pages.TotalPages}} 页，当前第 {{pages.CurrentPage}} 页。
</div>
{% endpagination %}
</div>
</div>
在这个示例中，我们首先通过tagDetail获取当前标签的标题和描述。然后，tagDataList以type="page"模式获取文档，并定义了limit来控制每页的显示数量。紧接着，pagination标签利用tagDataList生成的分页数据，构建出一个完整且可导航的分页列表，极大地提升了用户在标签归档页面的浏览体验。
运营人员的小提示
作为网站运营者，合理使用tagDataList不仅能丰富网站内容展示，更能提升用户满意度和SEO表现。
建议您在后台维护标签时，确保标签名称具有描述性且与内容高度相关，避免创建过多冗余或内容稀疏的标签。同时，关注标签页的TDK设置，让搜索引擎更好地理解这些聚合页面的主题。高质量的标签页面能够有效增加网站的内链结构，提升整体的搜索引擎友好度。
常见问题解答
Q1: tagDataList和archiveList这两个标签在使用上有什么核心区别？
tagDataList主要用于根据标签（Tag）来聚合和展示文档，其核心筛选依据是文档所关联的标签ID。它非常适合构建标签归档页或在文章侧边栏展示同标签下的相关内容。而archiveList则是一个更通用的文档列表标签，它可以通过分类（CategoryId）、模型（ModuleId）、推荐属性（Flag）、搜索关键词（q）等多种条件来筛选和显示文档。简而言之，当您需要基于标签来组织内容时，选择tagDataList；当您需要基于分类或其他通用属性来列出文档时，archiveList更为适用。
Q2: 如何在Tag详情页面自动获取当前Tag的ID，而无需手动指定tagId参数？
当您在设计安企CMS的标签详情页（通常是tag/detail.html或`