`tagDataList`标签如何显示某个具体标签下的所有文档列表？

在安企CMS中管理和展示内容，标签（Tag）无疑是一个极为实用的工具。它能帮助我们更灵活地组织文档，实现多维度内容聚合，对于提升网站的SEO表现和用户体验都大有裨益。当我们需要在一个特定的标签页面，或者在网站的任意位置，展示某个具体标签下的所有文档列表时，tagDataList 标签就是我们不可或缺的利器。

标签（Tag）的妙用与tagDataList的核心功能

在日常的网站运营中，我们经常需要将内容进行分类和归档。分类通常是层级化的，而标签则提供了一种扁平化、主题式的关联方式。例如，一篇关于“安企CMS教程”的文章可以属于“技术文章”分类，同时打上“安企CMS”、“CMS教程”、“Go语言”等多个标签。当用户点击“Go语言”标签时，他们期望看到所有与Go语言相关的文档，无论这些文档属于哪个主分类。tagDataList 标签正是为了满足这一需求而设计的，它能够精确地根据指定的标签，提取并展示所有与之关联的文档。

使用 tagDataList 标签非常直观。它的基本语法结构是 {% tagDataList 变量名称 with tagId="1" %}。在这里，变量名称 是您自定义的一个名称，用于在随后的循环中访问获取到的文档数据。tagId 参数是核心，它告诉系统您想要获取哪个标签下的文档列表。这个ID可以在安企CMS后台的“文档标签”管理页面找到。

灵活配置，精准获取文档列表

tagDataList 标签提供了多种参数，让您可以更精细地控制文档列表的获取和展示：

  1. tagId：如前所述，这是指定标签ID的关键参数。如果您当前处于一个标签详情页（例如 tag/list.html 或 tag/index.html 模板），并且省略了 tagId 参数，tagDataList 会智能地自动识别当前页面的标签ID，并获取其下的文档。这极大地简化了标签页的模板开发。当然，如果您想在其他页面获取特定标签的文档，或者强制指定某个标签，您仍然需要明确设置 tagId="X"，其中X是该标签的数字ID。

  2. moduleId：安企CMS支持多种内容模型（如文章、产品）。如果您只希望显示特定内容模型下的文档，可以使用 moduleId 参数进行筛选。例如，moduleId="1" 可以只获取文章模型下的文档。

  3. order：文档的排序方式同样可以灵活控制。您可以根据文档ID（id desc 或 id asc）、浏览量（views desc）、或后台设置的自定义排序（sort desc）来对文档进行排序，以满足不同的展示需求。

  4. limit：这个参数用于控制显示文档的数量。比如 limit="10" 会显示最新的10条文档。它还支持更高级的“偏移量”模式，例如 limit="2,10" 表示从第2条文档开始，获取10条数据，这在一些特殊的布局中非常有用。

  5. type：当您需要为文档列表添加分页功能时，type="page" 是您的选择；如果只是简单地列出固定数量的文档，type="list" 则更为合适。选择 type="page" 后，您还需要配合 pagination 标签来共同实现分页效果。

  6. siteId：对于启用了多站点功能的安企CMS，如果您需要跨站点调用特定标签下的文档，可以通过设置 siteId 参数来实现。

遍历文档，展示丰富信息

当您使用 tagDataList 标签获取到文档列表后，通常需要配合 for 循环来遍历这些文档，并逐一展示它们的信息。在循环内部，每个文档都可以通过您自定义的变量（例如上面提到的 archives 中的 item）来访问其各项属性。

这些可用的文档属性非常丰富，包括：

  • Id：文档的唯一ID。
  • Title：文档标题。
  • Link：文档的详情页链接，可以直接用于创建超链接。
  • Description：文档的简要描述或摘要。
  • Logo：文档的封面首图地址。
  • Thumb：文档的封面缩略图地址。
  • CreatedTime：文档的发布时间（时间戳格式），通常需要结合 stampToDate 过滤器进行格式化显示，例如 {{stampToDate(item.CreatedTime, "2006-01-02")}}。
  • Views：文档的浏览量。
  • Category：文档所属分类的完整信息，包括分类ID、标题、链接等。
  • 自定义字段：如果您在后台内容模型中为文档定义了额外的自定义字段，也可以通过 {{item.您的自定义字段名}} 来直接访问和显示。

结合分页，优化用户体验

如果标签下的文档数量较多，为了避免页面过长，通常需要使用分页功能。当 tagDataList 的 type 参数设置为 page 时，它会返回一个包含分页信息的对象。此时，我们可以紧接着使用 pagination 标签来生成分页导航。

例如，一个典型的标签文档列表展示代码结构如下：

<div class="tag-documents-list">
    {# 使用tagDataList获取指定标签下的文档列表，并开启分页功能 #}
    {% tagDataList archives with type="page" limit="10" %}
        {% for item in archives %}
        <div class="document-item">
            <a href="{{ item.Link }}">
                <h3>{{ item.Title }}</h3>
                {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="document-thumb">
                {% endif %}
                <p>{{ 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>当前标签下暂无文档。</p>
        {% endfor %}
    {% endtagDataList %}

    {# 分页导航区域，仅当type="page"时有效 #}
    <div class="pagination-nav">
        {% pagination pages with show="5" %}
            <ul>
                {# 首页链接 #}
                <li {% if pages.FirstPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.FirstPage.Link }}">{{ pages.FirstPage.Name }}</a></li>
                {# 上一页链接 #}
                {% if pages.PrevPage %}
                <li><a href="{{ pages.PrevPage.Link }}">{{ pages.PrevPage.Name }}</a></li>
                {% endif %}
                {# 中间页码链接 #}
                {% for pageItem in pages.Pages %}
                <li {% if pageItem.IsCurrent %}class="active"{% endif %}><a href="{{ pageItem.Link }}">{{ pageItem.Name }}</a></li>
                {% endfor %}
                {# 下一页链接 #}
                {% if pages.NextPage %}
                <li><a href="{{ pages.NextPage.Link }}">{{ pages.NextPage.Name }}</a></li>
                {% endif %}
                {# 尾页链接 #}
                <li {% if pages.LastPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.LastPage.Link }}">{{ pages.LastPage.Name }}</a></li>
            </ul>
        {% endpagination %}
    </div>
</div>

通过上述示例，我们可以看到，tagDataList 标签不仅强大，而且在使用上也非常灵活。它能够满足从简单列表到复杂分页展示的各种需求，帮助我们高效地构建基于标签的内容聚合页面，从而优化网站的内容结构和用户浏览体验。

常见问题 (FAQ)

1. tagDataList 和 archiveList 这两个标签有什么区别？我应该在什么时候使用它们？

tagDataList 主要用于获取与特定“标签”关联的文档列表。它的核心是根据 tagId 来筛选内容，非常适合在标签详情页或需要展示某个特定标签内容聚合的区域使用。而 archiveList 是一个更通用的文档列表标签，它可以通过多种方式（如 categoryId 分类ID、moduleId 模型ID、flag 推荐属性、userId 作者ID、q 搜索关键词等）来筛选文档。您可以把 archiveList 看作是获取文档列表的“万能钥匙”，而 tagDataList 则是针对“标签”这一特定维度的更专业工具。在标签页面，推荐优先使用 tagDataList，因为它逻辑更清晰且能更好地配合标签的特定路由。

2. 在安企CMS的标签详情页，如何让tagDataList自动识别当前标签的ID，而不需要手动指定tagId？

这是一个非常便捷的特性。当您在安企CMS的标签详情页（例如，您模板目录中的 tag/list.html 或 tag/index.html 文件）中使用 tagDataList 标签时，如果省略了 tagId 参数，系统会智能地自动检测并使用当前页面URL所对应的标签ID来获取文档列表。这意味着您通常只需要写 {% tagDataList archives with type="page" limit="10" %} 即可，无需手动查找和硬编码 tagId。只有当您希望在非标签详情页展示某个特定标签的文档，或者希望获取 其他 标签的文档时，才需要明确指定 tagId="X"。

3. 如何在 tagDataList 循环中显示文档的自定义字段？

在 tagDataList 循环中，您可以通过 item 变量直接访问文档的所有默认字段和自定义字段。如果您的文档模型中定义了一个名为 product_number 的自定义字段，您可以在循环内直接使用 {{ item.product_number }} 来显示其值。安企CMS会将这些自定义字段作为文档对象的一部分提供。对于更复杂的自定义字段类型（如图片组或富文本），可能需要结合使用其他过滤器（如 |safe 用于HTML内容）或辅助标签来正确渲染。