`tagDataList`标签如何根据特定标签获取并显示关联的文档列表？

在安企CMS中，标签（Tag）不仅仅是内容管理的一个辅助工具，更是连接不同主题内容、提升网站内部链接结构和优化用户体验的强大利器。当您希望在网站的某个页面，比如一个专题页、一个标签云页，或者某个特定文章的侧边栏，展示与某个特定标签相关的所有文档列表时，tagDataList 标签就是您的不二之选。

本文将深入探讨tagDataList标签如何根据特定标签灵活获取并显示关联的文档列表，帮助您更好地利用安企CMS进行内容运营。

tagDataList：连接内容与标签的核心桥梁

在安企CMS中，tagDataList标签的核心作用是根据您指定的标签ID，筛选出所有被该标签标记的文档，并将这些文档以列表的形式展示出来。这对于构建个性化的内容聚合页面、强化某一主题内容的曝光，以及提升用户在网站上的浏览深度都至关重要。

使用tagDataList标签时，通常会像这样组织您的模板代码：{% tagDataList archives with tagId="1" %}。这里的archives是我们自定义的一个变量名，用于存储从数据库中获取到的文档列表集合。您可以根据需要为其指定任何有意义的名称。随后，您就可以通过一个for循环来遍历archives中的每一个文档，并从中提取诸如文档标题、链接、简介、发布时间、缩略图等信息进行展示。

值得注意的是，tagDataList获取到的每一个文档对象，都拥有丰富的字段信息，例如：文档ID (Id)、标题 (Title)、SEO标题 (SeoTitle)、链接 (Link)、描述 (Description)、分类ID (CategoryId)、浏览量 (Views)、封面缩略图 (Thumb)、创建时间 (CreatedTime)等等。这些字段足以满足您在前端展示的各种需求。

深入理解tagDataList的参数

tagDataList标签提供了多个参数，让您能够精准控制所获取文档的范围和显示方式：

• tagId (标签ID)： 这是tagDataList标签最关键的参数。它指定了您希望获取哪个标签下的文档列表。这个ID可以在安企CMS后台的“内容管理” -> “文档标签”页面找到。如果您当前正处于一个标签详情页（例如，URL中包含某个标签的ID或别名），并且没有明确指定tagId，tagDataList标签会智能地自动读取当前页面的标签ID。当然，您也可以通过{% tagDetail with name="Id" %}这样的标签来动态获取当前标签页的ID，然后将其赋值给tagId参数，实现更灵活的调用。

• moduleId (模型ID)： 安企CMS支持灵活的内容模型，如“文章”模型（通常ID为1）、“产品”模型（通常ID为2）等。如果您只想显示特定内容模型下的标签关联文档，比如仅显示“文章”模型的文档，可以通过设置moduleId="1"来筛选。这对于避免不同类型内容混淆展示非常有用。

• order (排序方式)： 内容的排列顺序对用户体验和信息传达至关重要。order参数允许您自定义文档的排序规则。常见的排序方式包括：order="id desc"（按ID倒序，通常表示最新发布）、order="views desc"（按浏览量倒序，显示最热门的文档）、order="sort desc"（按后台自定义排序倒序）等。如果您不指定此参数，系统通常会按照默认的自定义排序规则进行展示。

• limit (显示数量)： 您可以控制一次性显示多少条文档。例如，limit="10"将只显示前10条文档。在某些场景下，您可能需要跳过前面几条，从中间开始显示，这时可以使用offset模式，如limit="2,10"表示从第2条开始，获取10条数据。

• type (列表类型)： 这是一个非常重要的参数，它决定了文档列表是以简单列表形式展示，还是为分页功能做准备。当您设置为type="list"时，tagDataList会直接输出指定limit数量的文档。而当您设置为type="page"时，它会为后续的分页标签pagination做好数据准备，让您能够轻松实现带有页码的文档列表展示。

• siteId (站点ID)： 安企CMS支持多站点管理。如果您在后台创建了多个站点，并且希望在一个站点中调用另一个站点的标签关联文档，可以通过指定siteId来实现。但在多数单站点运营场景下，通常无需设置此参数。

实践：在模板中运用tagDataList

让我们通过几个具体的模板代码示例，来理解tagDataList的实际应用。

示例一：显示某个固定标签下的最新5篇文档列表

假设您有一个标签ID为“1”的标签，希望在首页或侧边栏显示其下的最新5篇文档：

<div class="tag-related-articles">
    <h3>“热门话题”标签下的最新文章</h3>
    <ul>
        {% tagDataList archives with tagId="1" order="id desc" limit="5" %}
            {% for item in archives %}
                <li>
                    <a href="{{ item.Link }}" title="{{ item.Title }}">
                        {% if item.Thumb %}<img src="{{ item.Thumb }}" alt="{{ item.Title }}">{% endif %}
                        <h4>{{ item.Title }}</h4>
                        <p>{{ item.Description|truncatechars:80 }}</p>
                        <small>发布于: {{ stampToDate(item.CreatedTime, "2006-01-02") }}</small>
                    </a>
                </li>
            {% empty %}
                <li>当前标签下没有找到任何文档。</li>
            {% endfor %}
        {% endtagDataList %}
    </ul>
</div>

这段代码会查询标签ID为1的最新5篇文档，并以列表形式展示它们的标题、链接、缩略图、简介和发布日期。truncatechars:80是一个过滤器，用于将文档简介截取到80个字符并添加省略号。

示例二：在标签详情页显示该标签下的分页文档列表

当用户访问一个标签的专属页面时（例如/tag/seo），我们通常希望展示所有与“SEO”标签相关的文档，并提供分页功能。在这种情况下，tagDataList的type="page"参数就派上用场了：

”`twig {% tagDetail currentTag with name=“Id” %} {# 获取当前标签页的ID #} {% if currentTag %}

<div class="tag-documents-list">
    <h1>标签：{% tagDetail with name="Title" %}</h1>
    <p>描述：{% tagDetail with name="Description" %}</p>

    {% tagDataList archives with tagId=currentTag type="page" limit="10" %}
        {% for item in archives %}
            <article>
                <a href="{{ item.Link }}" title="{{ item.Title }}">
                    <h2>{{ item.Title }}</h2>
                    <p>{{ item.Description|truncatechars:150 }}</p>
                    <small>浏览量: {{ item.Views }} | 发布于: {{ stampToDate(item.CreatedTime, "2006-01-02") }}</small>
                </a>
            </article>
        {% empty %}
            <p>当前标签下没有找到任何文档。</p>
        {% endfor %}
    {% endtagDataList %}

    <div class="pagination-container">
        {% pagination pages with show="5" %}
            <ul>
                {% if pages.FirstPage %}
                    <li class="{% if pages.FirstPage.IsCurrent %}active{% endif %}"><a href="{{pages.FirstPage.Link}}">首页</a></li>
                {% endif %}
                {% if pages.PrevPage %}
                    <li><a href="{{pages.PrevPage.Link}}">上一页</a></li>
                {% endif %}
                {% for pageItem in pages.Pages %}
                    <li class="{% if pageItem.IsCurrent %}active{% endif %}"><a href="{{pageItem.Link}}">{{pageItem.Name}}</a></li>
                {% endfor %}
                {% if pages.NextPage %}
                    <li><a href="{{pages.NextPage.Link}}">下一页</a></li>
                {% endif %}
                {% if pages.LastPage %}
                    <li class="{% if pages.LastPage.IsCurrent %}active{% endif %}"><a href="{{pages.LastPage.Link}}">尾页</a></li>
                {% endif %}
            </ul>
        {% endpagination %}
    </div>
</div>

{% else %}

<p>未能找到相关标签信息