如何列出指定Tag标签下的所有相关文档列表？

作为一位深谙安企CMS运营之道的网站内容专家，我深知读者对高效内容管理和展示的渴求。标签（Tags）作为内容组织的重要手段，能够极大地提升内容的可发现性和用户体验。在安企CMS中，正确地利用标签功能，能帮助您的网站实现更精细化的内容聚合与分发。

本篇文章将详细阐述如何在安企CMS中列出指定Tag标签下的所有相关文档列表，帮助您更好地组织和呈现网站内容。

深入理解安企CMS的标签功能

安企CMS的标签功能旨在为内容提供灵活的话题分类。与严格的分类（Category）不同，标签更像是内容的关键词或主题词，允许一篇文档关联多个标签，从而在不同维度上实现内容之间的交叉引用。后台的文档标签管理功能，允许您创建、编辑和管理这些标签，并将其应用于文章、产品等各类文档。这种机制使得内容的组织更加灵活，也为用户提供了多样的内容探索路径。

核心模板标签：tagDataList 的使用

要在网站前端列出指定Tag标签下的所有相关文档，安企CMS提供了专门的模板标签tagDataList。这个标签是您实现此功能的关键工具，它能够根据您提供的标签ID，检索并返回所有关联的文档列表。

tagDataList 标签的基本语法与参数

tagDataList 标签的基本使用方式是：{% tagDataList archives with tagId="1" %}...{% endtagDataList %}。在这里，archives 是一个自定义的变量名称，它将承载从标签检索到的文档集合。

该标签支持多个参数，以满足不同的内容展示需求：

  • tagId：指定标签ID 这是最核心的参数，用于明确您想列出哪个标签下的文档。例如，tagId="1" 将列出ID为1的标签下的所有文档。需要注意的是，如果在不指定 tagId 的情况下，此标签会自动尝试读取当前Tag页面的TagID，这在构建标签详情页时非常方便。

  • moduleId：按内容模型筛选 如果您希望只列出特定内容模型（如文章、产品）下的文档，可以使用此参数。例如，moduleId="1" 将仅获取文章模型下的文档。

  • order：排序规则 您可以根据需求设定文档的排序方式，例如 order="id desc" 按最新发布排序，order="views desc" 按浏览量从高到低排序，或者 order="sort desc" 按后台自定义排序。

  • limit：控制显示数量 此参数用于限制返回的文档数量。limit="10" 将显示10条文档。它还支持 offset 模式，例如 limit="2,10" 表示从第2条文档开始，获取10条数据。

  • type：列表类型 type 参数决定了列表的展示行为。默认值为 list，此时 limit 参数将精确控制返回的文档数量。如果设置为 type="page"，则表示您希望启用分页功能，后续可以结合 pagination 标签来构建完整的翻页界面。

  • siteId：多站点调用 在安企CMS的多站点管理模式下，如果您需要调用其他站点的数据，可以通过指定 siteId 参数来实现。通常情况下，此参数无需填写。

tagDataList 标签会返回一个 archives 数组对象，您需要通过 for 循环来遍历并展示其中的每一个文档。每个 item 对象（即数组中的每一篇文档）都包含了丰富的字段信息，例如：Id（文档ID）、Title（文档标题）、Link（文档链接）、Description（文档描述）、Logo（封面首图）、Thumb（缩略图）、CreatedTime（创建时间）、Views（浏览量）等。您可以根据模板设计，灵活地选用这些字段来构建文档列表。

实战演示：列出指定Tag下的文档列表

通常情况下，显示指定标签下的文档列表最常用的场景是标签详情页 (tag/list.html 或 tag_list.html)，或者在某个页面的侧边栏或底部区域展示相关推荐。

示例一：在标签详情页显示分页文档列表

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

{# 页面标题可以显示当前标签的名称 #}
<h1>标签：{% tagDetail with name="Title" %}</h1>
<p>描述：{% tagDetail with name="Description" %}</p>

<div class="document-list">
    {# 使用tagDataList标签，type="page"开启分页功能 #}
    {% tagDataList archives with type="page" limit="10" %}
        {% for item in archives %}
        <div class="document-item">
            <a href="{{item.Link}}">
                {% if item.Thumb %}
                <img src="{{item.Thumb}}" alt="{{item.Title}}" class="document-thumbnail">
                {% endif %}
                <h2 class="document-title">{{item.Title}}</h2>
            </a>
            <p class="document-description">{{item.Description}}</p>
            <div class="document-meta">
                {# 获取文档所属分类的标题 #}
                <span>分类：{% categoryDetail with name="Title" id=item.CategoryId %}</span>
                {# 格式化文档发布时间 #}
                <span>发布时间：{{stampToDate(item.CreatedTime, "2006-01-02")}}</span>
                <span>浏览量：{{item.Views}}</span>
            </div>
        </div>
        {% empty %}
        <p>该标签下没有任何文档。</p>
        {% endfor %}
    {% endtagDataList %}

    {# 引入分页导航 #}
    <div class="pagination-container">
        {% pagination pages with show="5" %}
            <ul>
                <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>
        {% endpagination %}
    </div>
</div>

在这个示例中，tagDataList 自动获取当前标签页面的 tagId，并以每页10条的形式展示文档。pagination 标签则负责渲染完整的翻页导航。通过 item.CategoryId 和 categoryDetail 标签的结合，我们还能在文档列表中显示每篇文档所属的分类名称。

示例二：在侧边栏显示指定标签下的最新文档

如果您想在网站的某个固定区域，例如侧边栏，展示某个特定标签下的最新5篇文档，您可以这样做：

<div class="sidebar-block">
    <h3>“Go语言”标签下的最新文档</h3>
    <ul>
        {# 假设标签ID为10，获取最新5篇文档 #}
        {% tagDataList archives with tagId="10" order="id desc" limit="5" %}
            {% for item in archives %}
            <li>
                <a href="{{item.Link}}">{{item.Title}}</a>
                <span>({{stampToDate(item.CreatedTime, "01-02")}})</span>
            </li>
            {% empty %}
            <li>暂无相关文档。</li>
            {% endfor %}
        {% endtagDataList %}
    </ul>
</div>

这个例子展示了如何明确指定 tagId 和 limit 参数，以实现精准的内容推荐。

通过灵活运用 tagDataList 标签及其参数，您可以根据网站的实际需求，在安企CMS中创建出各种形式的标签文档列表，极大地丰富您的内容展示方式，并优化用户的浏览体验。

常见问题解答 (FAQ)

  • tagList 和 tagDataList 两个标签有什么区别？ tagList 标签主要用于获取“标签本身的列表”，例如，您可能想在网站底部或侧边栏显示所有热门标签的云图，或者在标签首页列出所有标签名称。它返回的是一系列标签对象（包含标签ID、标题、链接等）。而 tagDataList 标签则用于获取“指定标签下的文档列表”，也就是根据一个或多个标签，找出所有被这些标签标记的文档内容。简而言之，tagList 关注的是标签本身，tagDataList 关注的是标签所关联的文档。

  • 如何在标签文档列表中显示每篇文档的所属分类信息？ 在通过 tagDataList 标签循环遍历文档时，每个 item 对象中都包含了 CategoryId 字段，即该文档所属分类的ID。您可以结合 categoryDetail 标签，根据这个 CategoryId 来获取并显示分类的详细信息，例如分类标题或分类链接。具体的用法是在 tagDataList 循环内部，使用 {% categoryDetail with name="Title" id=item.CategoryId %} 来获取分类标题。

  • 我能否同时列出多个指定标签下的文档列表？ 根据安企CMS的当前模板标签设计，tagDataList 标签的 tagId 参数仅支持指定单个标签ID。如果您需要同时列出多个特定标签下的文档，目前无法直接通过一个 tagDataList 调用实现。通常的解决方案是，您可以多次使用 tagDataList 标签，为每个需要展示的标签分别调用一次；或者，如果您有更复杂的聚合需求，可能需要通过二次开发，在后端控制器中进行更复杂的查询逻辑，然后将结果传递给前端模板进行渲染。