AnQiCMS 的 `tagDataList` 标签如何根据指定的 Tag ID 显示相关文章列表？

在安企CMS中管理和展示内容，尤其是在需要根据特定主题或关键词聚合文章时，标签（Tag）功能显得尤为重要。它不仅能帮助访问者快速找到感兴趣的内容，还能有效提升网站的内部链接结构和SEO表现。今天，我们来深入了解一下 AnQiCMS 中一个非常实用的模板标签：tagDataList，看看它如何根据指定的 Tag ID 精准地展示相关文章列表。

核心功能解析：tagDataList 标签的基础用法

AnQiCMS 提供了丰富且灵活的模板标签，tagDataList 便是其中之一，专门用于从数据库中提取与特定标签关联的文章（或文档）列表。想象一下，你有一个关于“搜索引擎优化”的标签，想在某个页面展示所有带有这个标签的文章，tagDataList 就是实现这一目标的关键。

它的基本用法非常直观：

{% tagDataList archives with tagId="1" %}
    {% for item in archives %}
        <div class="article-item">
            <h3><a href="{{ item.Link }}">{{ item.Title }}</a></h3>
            <p>{{ item.Description|truncatechars:100 }}</p>
            <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
        </div>
    {% empty %}
        <p>当前标签下暂无文章。</p>
    {% endfor %}
{% endtagDataList %}

在这段代码中：

  • tagDataList archives：我们定义了一个名为 archives 的变量，所有符合条件的文章数据都将存储在这个变量中。你可以根据自己的习惯命名这个变量。
  • with tagId="1"：这是 tagDataList 最核心的参数，它明确指定了我们想要获取哪个 Tag ID 下的文章。你需要将 "1" 替换为你实际想要调用的标签的 ID。
  • {% for item in archives %}：由于 archives 是一个文章列表（数组对象），我们需要通过 for 循环来逐一遍历并展示每篇文章。在循环内部，item 变量代表当前文章的所有字段，例如 item.Title（文章标题）、item.Link（文章链接）、item.Description（文章描述）等。
  • {% empty %}：这是一个非常人性化的设计。如果 archives 列表中没有任何文章，empty 块内的内容就会被显示出来，避免页面出现空白或报错。
  • {% endtagDataList %}：与 tagDataList 成对出现，表示标签作用域的结束。

如何获取 Tag ID？ 你可以在 AnQiCMS 后台的“内容管理” -> “文档标签”页面，查看每个标签的详细信息，其中通常会包含其唯一的 ID。另外，在标签详情页面的模板（通常是 tag/detail.html）中，tagDataList 标签如果省略 tagId 参数，它会智能地自动读取当前页面的 Tag ID，从而显示与当前标签页关联的文章列表。

灵活控制内容：tagDataList 的关键参数

除了 tagId，tagDataList 还提供了一系列参数，帮助我们更精细地控制文章的获取和展示：

  1. moduleId：指定内容模型 AnQiCMS 支持灵活的内容模型，如“文章”模型（默认 ID 可能为 1）和“产品”模型（默认 ID 可能为 2）。如果你只想显示某个特定内容模型下的文章，可以使用 moduleId 参数。 例如，with tagId="1" moduleId="1" 将只获取 Tag ID 为 1 的“文章”模型下的文章。

  2. limit：控制显示数量 这个参数用于控制显示的文章数量。如果你只想显示最新的 5 篇文章，可以设置 limit="5"。它也支持偏移量，比如 limit="2,10" 会从第 2 篇文章开始，显示接下来的 10 篇文章。

  3. order：排序方式 文章的显示顺序可以通过 order 参数来控制。常见的排序方式有：

    • order="id desc"：按 ID 倒序（最新发布）。
    • order="views desc"：按浏览量倒序（最热门）。
    • order="sort desc"：按后台自定义排序倒序。

  4. type 与 pagination：列表类型与分页

    • type="list" (默认值)：当只希望显示固定数量的文章时使用，不带分页功能。
    • type="page"：当希望显示文章列表并支持分页时使用。在这种情况下，你需要结合 pagination 标签来构建分页导航。

  5. siteId：多站点兼容 如果你在使用 AnQiCMS 的多站点管理功能，并且需要调用其他站点的数据，可以通过 siteId 参数来指定。对于单站点用户，通常无需设置此参数。

实践案例：构建 Tag 相关文章列表

让我们通过一个更完整的例子，看看如何在实际模板中应用 tagDataList。

案例一：在非标签页展示热门标签的文章列表

假设我们想在网站首页的一个侧边栏，展示“SEO优化”标签下的最新3篇文章。

{# 假设 Tag ID 为 10 代表“SEO优化”标签 #}
<h2>热门SEO文章</h2>
{% tagDataList archives with tagId="10" moduleId="1" order="id desc" limit="3" %}
    <ul>
    {% for item in archives %}
        <li>
            <a href="{{ item.Link }}" title="{{ item.Title }}">
                {{ item.Title|truncatechars:25 }}
            </a>
            <p class="post-date">{{ stampToDate(item.CreatedTime, "2006-01-02") }}</p>
        </li>
    {% empty %}
        <li>暂无相关文章。</li>
    {% endfor %}
</ul>
{% endtagDataList %}

这里，我们通过 moduleId="1" 确保只获取文章，order="id desc" 保证是最新的，limit="3" 则限制了显示数量。

案例二：在 Tag 详情页展示分页文章列表

当用户点击一个标签进入其详情页（例如 tag/list.html 或 tag/index.html）时，通常需要显示该标签下的所有文章，并提供分页功能。

{# 假设当前页面是 Tag 详情页，tagId 会自动获取 #}
<h1>标签：{% tagDetail with name="Title" %} 相关文章</h1>
<div class="tag-description">
    <p>{% tagDetail with name="Description" %}</p>
</div>

<div class="article-list">
{% tagDataList archives with type="page" limit="10" %} {# 每页显示10篇文章 #}
    {% for item in archives %}
        <div class="article-card">
            <a href="{{ item.Link }}">
                {% if item.Thumb %}
                    <img src="{{ item.Thumb }}" alt="{{ item.Title }}" class="article-thumb">
                {% else %}
                    {# 可以放置一个默认缩略图 #}
                    <img src="/static/images/default-thumb.png" alt="默认图片" class="article-thumb">
                {% endif %}
                <h3>{{ item.Title }}</h3>
            </a>
            <p>{{ item.Description|truncatechars:120 }}</p>
            <div class="article-meta">
                <span>分类：<a href="{% categoryDetail with name='Link' id=item.CategoryId %}">{% categoryDetail with name='Title' id=item.CategoryId %}</a></span>
                <span>发布：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                <span>阅读：{{ item.Views }}</span>
            </div>
        </div>
    {% empty %}
        <p>当前标签下还没有任何文章。</p>
    {% endfor %}
{% endtagDataList %}
</div>

{# 分页导航 #}
<div class="pagination-nav">
    {% pagination pages with show="5" %} {# 最多显示5个页码按钮 #}
        {% if pages.PrevPage %}
            <a href="{{ pages.PrevPage.Link }}" class="prev">上一页</a>
        {% endif %}
        {% for pageItem in pages.Pages %}
            <a href="{{ pageItem.Link }}" class="page-number {% if pageItem.IsCurrent %}active{% endif %}">{{ pageItem.Name }}</a>
        {% endfor %}
        {% if pages.NextPage %}
            <a href="{{ pages.NextPage.Link }}" class="next">下一页</a>
        {% endif %}
    {% endpagination %}
</div>

在这个案例中，tagDataList archives with type="page" limit="10" 会获取当前