轻松展示文档关联标签：AnQiCMS 的 tagList 标签深度解析

在内容管理中，标签（Tag）扮演着至关重要的角色。它们不仅能帮助我们更好地组织内容，提升网站的内部链接结构，还能在搜索引擎优化（SEO）方面发挥巨大作用，让用户和搜索引擎更容易发现相关信息。AnQiCMS 充分考虑到了这一点，提供了一套灵活且功能强大的标签管理系统。其中，tagList 标签正是我们前端展示文档关联标签的核心工具。

核心功能解析：tagList 标签概览

tagList 标签的主要用途是获取并展示文档所关联的所有标签。无论是为了在文章底部显示相关话题，还是在侧边栏创建一个热门标签云，tagList 都能提供我们所需的数据。这个标签允许我们根据不同的需求，灵活地控制标签的来源和数量。

如何为文档关联标签

在使用 tagList 标签之前，我们需要了解标签是如何与文档关联起来的。在 AnQiCMS 的后台，当我们添加或编辑一篇文档时，会看到一个“Tag标签”的输入框。在这里，我们可以为当前文档添加多个标签。我们可以选择已存在的标签，也可以通过输入文字并按回车键来创建新的标签。AnQiCMS 的标签系统非常灵活，同一个标签可以被不同内容模型（如文章、产品等）的文档所共用，这意味着标签是跨分类、跨模型的。

tagList 标签的基础用法

tagList 标签的使用遵循 AnQiCMS 模板引擎的统一语法。它的基本结构是 {% tagList 变量名 with ... %} 和 {% endtagList %}。

例如，要在前端展示当前文档的所有标签，我们可以这样定义一个变量 tags 来承载这些标签数据，然后通过 for 循环遍历输出：

<div>
    文档标签：
    {% tagList tags %}
        {% for item in tags %}
            <a href="{{item.Link}}">{{item.Title}}</a>
        {% endfor %}
    {% endtagList %}
</div>

在这个例子中，tags 是一个数组对象，for 循环中的 item 变量则代表了每一个独立的标签对象。每个标签对象都包含了 Id（标签ID）、Title（标签名称）、Link（标签链接）、Description（标签描述）以及 FirstLetter（标签索引字母）等信息。我们可以根据需要，通过 item.属性名 的方式来访问和展示这些数据。

深入理解 tagList 的参数

tagList 标签提供了多个参数，让我们可以更精细地控制标签的获取：

  • itemId：指定文档 ID 默认情况下，tagList 会自动获取当前页面文档所关联的标签。但如果我们想展示特定文档的标签，可以通过 itemId="文档ID" 来指定。例如，itemId="10" 会获取 ID 为 10 的文档的标签。如果想展示所有标签，而不是与特定文档关联的标签，可以将 itemId 设置为 0，即 itemId="0"。这在制作网站的标签云或热门标签列表时非常有用。

  • limit：控制显示数量 我们可以通过 limit="数量" 来限制显示的标签数量。例如，limit="10" 会只显示最多 10 个标签。如果我们需要从某个位置开始获取一定数量的标签（例如，从第 2 个标签开始获取 5 个），可以采用 limit="offset,数量" 的模式，例如 limit="2,5"。

  • letter：按索引字母筛选 这个参数允许我们只显示特定首字母的标签，例如 letter="A" 会只显示以 A 开头的标签。

  • categoryId：按分类 ID 筛选 如果我们希望只显示某个或某几个特定分类下的标签（这些标签可能同时关联到其他分类的文档，但在这里我们只关心特定分类上下文中的标签），可以使用 categoryId="分类ID"。多个分类 ID 可以用英文逗号 , 分隔，例如 categoryId="1,2,3"。

  • siteId：多站点数据调用 对于那些使用了 AnQiCMS 多站点管理功能的用户，如果需要调用其他站点的数据，可以通过 siteId="站点ID" 来指定。通常情况下，这个参数可以省略，因为 tagList 会默认获取当前站点的数据。

实用代码示例

了解了参数，我们来看看一些更具体的应用场景。

1. 显示当前文档关联的所有标签

<div class="article-tags">
    <strong>相关标签：</strong>
    {% tagList currentDocTags %}
        {% for tag in currentDocTags %}
            <a href="{{ tag.Link }}" title="{{ tag.Title }}">{{ tag.Title }}</a>
        {% empty %}
            <span>暂无相关标签</span>
        {% endfor %}
    {% endtagList %}
</div>

2. 显示所有热门标签（例如，在侧边栏）

这里我们将 itemId 设置为 0，并限制显示数量。

<div class="sidebar-tags">
    <h4>热门标签</h4>
    <ul>
        {% tagList hotTags with itemId="0" limit="15" %}
            {% for tag in hotTags %}
                <li><a href="{{ tag.Link }}">{{ tag.Title }}</a></li>
            {% empty %}
                <li>暂无热门标签</li>
            {% endfor %}
        {% endtagList %}
    </ul>
</div>

3. 在专门的标签列表页进行分页显示

AnQiCMS 的 tagList 标签也支持分页功能，这通常用于 /tag/index.html 这样的标签索引页面。我们需要将 type 参数设置为 "page"，并结合 pagination 标签使用。

”`twig 

<h1>所有标签</h1>
{% tagList allPageTags with type="page" limit="20" %}
    <ul class="tag-grid">
    {% for tag in allPageTags %}
        <li>
            <a href="{{ tag.Link }}" title="{{ tag.Title }}">
                <h3>{{ tag.Title }}</h3>
                {% if tag.Description %}
                    <p>{{ tag.Description | truncatechars: 100 }}</p>
                {% endif %}
            </a>
        </li>
    {% empty %}
        <li>暂无标签可显示。</li>
    {% endfor %}
    </ul>

    {# 分页代码 #}
    <div class="pagination-nav">
        {% 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 p_item in pages.Pages %}
                    <li class="page-item {% if p_item.IsCurrent %}active{% endif %}"><a href="{{p_item.Link}}">{{p_item.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>