如何在Tag详情页，获取并显示该Tag下所有相关的文档列表？

在内容运营中，标签（Tag）是一个极其重要的工具，它能够帮助我们有效地组织内容，提升网站内部链接的质量，并最终改善用户的浏览体验和搜索引擎的抓取效率。通过为文章、产品或其他内容打上相关标签，我们可以将散落在不同分类中的同主题内容关联起来，形成更紧密的知识网络。

那么，当用户点击某个特定的标签时，我们如何才能在Tag详情页上，清晰地展示所有与该标签关联的文档列表呢？安企CMS提供了一套直观而强大的模板标签系统，让这个过程变得非常简单。

搭建Tag详情页的基础

首先，我们需要明确Tag详情页通常位于网站模板的特定位置。根据安企CMS的模板设计约定，Tag详情页的模板文件通常命名为 tag/list.html 或 tag/index.html。当你访问一个Tag详情页时，系统会自动识别当前页面的Tag信息，这为我们后续调用相关内容提供了便利。

获取Tag的详细信息（可选但推荐）

虽然我们的核心目标是展示文档列表，但在Tag详情页上，我们往往也需要显示当前Tag的名称、描述等信息，这有助于用户了解他们所浏览的页面主题。我们可以使用 tagDetail 标签来获取这些信息。

例如，要在页面顶部显示当前Tag的标题和描述，可以这样编写模板代码：

{% tagDetail currentTag with name="Title" %}
<h1>{{ currentTag }}</h1>

{% tagDetail tagDescription with name="Description" %}
{% if tagDescription %}
    <p>{{ tagDescription }}</p>
{% endif %}

在这里，tagDetail 标签会自动识别当前页面的Tag ID，并获取其对应的标题和描述。这使得页面内容更加丰富和用户友好。

核心操作：获取Tag下的文档列表

要获取并显示当前Tag下的所有相关文档，我们主要会用到 tagDataList 标签。这个标签专门设计用于在Tag上下文环境中调用与之关联的文档列表。

使用 tagDataList 标签非常直接。在Tag详情页的模板中，你可以这样引入它：

{% tagDataList archives with type="page" limit="10" %}
    {# 在这里循环显示文档列表 #}
{% endtagDataList %}

让我们详细解读一下这个标签的参数：

• archives: 这是一个自定义的变量名，你可以根据自己的习惯命名，它将承载从标签关联到的文档数据。在 {% for ... %} 循环中，你将通过这个变量来访问每个文档对象。
• type="page": 这个参数至关重要，它告诉安企CMS我们需要一个支持分页的文档列表。如果你的Tag下文档数量较多，分页能够显著提升页面加载速度和用户体验。如果不需要分页，只想显示固定数量的列表，可以使用 type="list"。
• limit="10": 这个参数定义了每页或每次调用显示的文档数量。你可以根据设计需求调整这个数字。
• tagId: 如果你在非Tag详情页（例如首页或分类页）需要调用特定Tag的文档列表，可以通过 tagId="X" （其中X是Tag的ID）来指定。但在Tag详情页上，tagDataList 会智能地自动获取当前页面的Tag ID，所以通常无需手动指定。
• moduleId: 如果你只想获取特定内容模型（如“文章”或“产品”）下的文档，可以指定 moduleId="1" (假设1是文章模型ID)。
• order: 你还可以通过 order="id desc" (按最新发布) 或 order="views desc" (按浏览量最多) 等方式来排序文档列表。

循环显示文档数据

一旦通过 tagDataList 标签获取到文档集合，我们就可以使用 for 循环来遍历 archives 变量，逐一展示每个文档的详细信息。在循环内部，每个 item 都代表一个文档对象，你可以访问它的各种属性，比如标题、链接、简介、发布时间、缩略图等。

<ul class="tag-document-list">
{% tagDataList archives with type="page" limit="10" %}
    {% for item in archives %}
    <li>
        <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
        <p>{{ item.Description }}</p>
        <div class="meta">
            <span>发布日期: {{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
            <span>浏览量: {{ item.Views }}</span>
            {% if item.Thumb %}
                <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="thumbnail">
            {% endif %}
        </div>
    </li>
    {% empty %}
    <li>当前标签下暂无相关文档。</li>
    {% endfor %}
</ul>

这里我们使用了 stampToDate 过滤器来将时间戳格式化成易读的日期。{% empty %} 块是一个非常有用的特性，它会在 archives 列表为空时显示指定的内容，避免页面空白。

实现分页功能

对于文档数量较多的Tag，分页是必不可少的。当你在 tagDataList 中设置 type="page" 后，我们就可以结合 pagination 标签来生成分页导航。

在 tagDataList 标签的 {% endtagDataList %} 之后，紧接着添加分页代码：

{# ... 上面的 tagDataList 和文档列表循环 ... #}

<div class="pagination-area">
    {% pagination pages with show="5" %}
    <nav aria-label="Page navigation">
        <ul class="pagination">
            {# 首页 #}
            <li class="page-item {% if pages.FirstPage.IsCurrent %}active{% endif %}">
                <a class="page-link" href="{{ pages.FirstPage.Link }}">{{ pages.FirstPage.Name }}</a>
            </li>
            {# 上一页 #}
            {% if pages.PrevPage %}
            <li class="page-item">
                <a class="page-link" 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 class="page-link" href="{{ pageItem.Link }}">{{ pageItem.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 %}
            {# 末页 #}
            <li class="page-item {% if pages.LastPage.IsCurrent %}active{% endif %}">
                <a class="page-link" href="{{ pages.LastPage.Link }}">{{ pages.LastPage.Name }}</a>
            </li>
        </ul>
    </nav>
    {% endpagination %}
</div>

这里 pages 变量包含了所有分页相关的数据，如当前页码、总页数、首页链接、上一页/下一页链接以及中间页码列表。show="5" 参数控制了中间页码最多显示5个。你可以根据需要调整布局和样式。

整合与优化

通过结合 tagDetail、tagDataList 和 pagination 标签，我们就能够构建一个功能完善、内容丰富的Tag详情页。别忘了在页面的 <head> 部分，使用 tdk 标签为Tag详情页设置合适的SEO标题、关键词和描述，这对于搜索引擎的收录和排名至关重要。

<head>
    <title>{% tdk with name="Title" siteName=true sep=" - " %}</title>
    <meta name="keywords" content="{% tdk with name="Keywords" %}">
    <meta name="description" content="{% tdk with name="Description" %}">
    {# 其他head内容 #}
</head>

合理利用标签功能，不仅能让你的网站内容组织得井井有条，更能为用户提供高效便捷的浏览路径，同时提升网站的整体SEO表现。安企CMS的模板标签系统正是为此而生，它赋予了内容运营者在不深入代码的情况下，灵活掌控网站内容展示的能力。

常见问题 (FAQ)

1. 我在Tag详情页上调用 tagDataList 后，为什么没有显示任何文档？

出现这种情况可能有几个原因。首先，请检查你的网站是否已经为文档分配了相应的Tag。进入文档编辑界面，确保“Tag标签”字段已填写并与当前Tag详情页的Tag正确关联。其次，确保 tagDataList 标签的 limit 参数没有设置得过小，导致没有内容显示。最后，如果你指定了 moduleId 或其他过滤条件，请确认这些条件是正确的，没有意外地将所有文档过滤掉。使用 {% empty %} 标签来处理无内容显示的情况，可以给用户一个友好的提示。

2. 如何自定义Tag详情页的URL伪静态规则？

安企CMS允许你通过后台的“伪静态规则”功能自定义URL结构。对于Tag详情页，通常会有类似 /tag/{id} 或 /tags/{name} 的结构。你可以在后台选择内置的伪静态规则，或者在“自定义模式”下，找到 tag 或 tagIndex 对应的规则项进行编辑。例如，将 tagIndex===/tags(-{page}) 或 tag===/tag-{id}(-{page}) 修改为更符合你需求的格式。在修改后，请务必更新缓存并检查新URL是否生效。

3. 除了显示文档列表，我还可以在Tag详情页上显示哪些与Tag相关的信息？

除了文档列表，你还可以利用 tagDetail 标签获取当前Tag的更多详细信息。例如，{% tagDetail tagLogo with name="Logo" %} 可以获取Tag的Logo图片，{% tagDetail tagContent with name="Content" %} 可以获取Tag的自定义内容。这些信息可以用来丰富Tag详情页的视觉呈现和信息量，使其不仅是文档列表，更是一个独立的、有价值的专题页面。