如何在AnQiCMS模板中获取并展示指定分类下的所有文章列表？

在AnQiCMS中构建网站时，我们经常需要根据特定的内容分类来展示文章列表，无论是博客的文章分类、产品分类，还是新闻分类。这不仅有助于网站内容的组织，也能提升用户浏览体验和搜索引擎的友好度。AnQiCMS提供了强大且灵活的模板标签，让这一需求变得简单直观。

AnQiCMS的模板系统采用了类似Django模板引擎的语法，以Go语言为底层支持，保证了模板解析的高效性。在模板文件中，我们通常会使用双花括号{{变量}}来输出变量内容，而使用单花括号和百分号{% 标签 %}来调用功能性标签，例如条件判断和循环控制。所有模板文件都统一存放在/template目录下，并使用UTF-8编码，确保内容正确显示。

核心标签：archiveList深度解析

要获取并展示指定分类下的所有文章列表，AnQiCMS的核心是archiveList标签。这个标签专门用于查询和输出不同内容模型下的文档列表。理解其参数是成功实现目标的关键。

archiveList标签的基本使用方式是这样的： {% archiveList 变量名称 with 参数1="值1" 参数2="值2" %}...{% endarchiveList %} 其中，“变量名称”是我们为获取到的文章列表定义的一个临时变量，通常命名为archives，方便在for循环中遍历。

以下是一些在使用archiveList时常用的关键参数：

  1. moduleId (模型ID)： 在AnQiCMS中，文章、产品等都属于不同的“内容模型”。每个模型都有一个唯一的ID。例如，如果我们要获取“文章”模型下的文章，可能需要指定moduleId="1"（具体ID可在后台“内容管理”->“内容模型”中查看）。这是因为分类是依附于特定内容模型的。
  2. categoryId (分类ID)： 这是指定要获取哪个分类文章的核心参数。你可以传入一个具体的分类ID，例如categoryId="10"。如果需要获取多个分类的文章，可以使用逗号分隔多个ID，如categoryId="10,11,12"。值得注意的是，如果你在分类列表页面（即URL中已包含分类ID）不指定此参数，archiveList会自动尝试读取当前页面的分类ID。如果你想避免这种自动读取行为，可以明确设置categoryId="0"。
  3. type (列表类型)： 这个参数决定了文章列表的展示方式。
    • type="list"：用于获取固定数量的文章列表，配合limit参数使用。
    • type="page"：用于获取支持分页的文章列表，通常与pagination标签结合使用，以显示页码导航。
  4. limit (显示数量)： 当type="list"时，此参数指定要显示的文章数量，例如limit="10"表示显示10篇文章。它还支持offset,count的模式，例如limit="2,10"表示从第3篇文章开始显示10篇文章（跳过前2篇）。
  5. order (排序方式)： 我们可以根据不同的需求对文章进行排序。常用的排序值有：
    • id desc：按照文章ID降序排列（最新发布的文章在前）。
    • views desc：按照浏览量降序排列（最热门的文章在前）。
    • sort desc：按照后台设置的自定义排序值降序排列。
  6. child (是否包含子分类)： 默认情况下，child参数为true，表示获取指定分类及其所有子分类下的文章。如果只想显示当前指定分类下的文章，而不包括子分类的，可以设置为child=false。
  7. siteId (站点ID)： 如果您的AnQiCMS部署了多站点，并且希望获取其他站点的数据，可以通过此参数指定。一般情况下，无需设置。

当archiveList标签获取到文章列表后，它会赋值给您定义的变量（例如archives），这个变量是一个数组对象。在模板中，您可以使用{% for item in archives %}循环遍历这个数组，item就代表了数组中的每一篇文章。

每篇文章(item)对象包含以下常用字段：

  • Id：文章ID
  • Title：文章标题
  • Link：文章详情页链接
  • Description：文章简介
  • Content：文章内容（通常在详情页使用，列表页一般只显示简介）
  • CategoryId：文章所属分类ID
  • Views：文章浏览量
  • CreatedTime：文章发布时间（时间戳格式，需要用stampToDate标签格式化）
  • Thumb：文章缩略图地址
  • Logo：文章封面首图地址
  • 以及在“内容模型”中自定义的其他字段。

实战演练：获取并展示文章列表

了解了archiveList标签的各项参数后，我们来看几个实际应用场景。

场景一：展示固定分类下的最新文章列表（不分页）

假设我们要在首页的一个区块中显示“公司新闻”分类（分类ID为5，属于文章模型，模型ID为1）的最新5篇文章。

<div class="news-section">
    <h2>公司新闻</h2>
    <ul>
        {% archiveList archives with moduleId="1" categoryId="5" order="id desc" limit="5" %}
            {% for item in archives %}
            <li>
                <a href="{{ item.Link }}">
                    <img src="{{ item.Thumb }}" alt="{{ item.Title }}" {% if not item.Thumb %}style="display:none;"{% endif %}>
                    <h3>{{ item.Title }}</h3>
                    <p>{{ item.Description|truncatechars:80 }}</p> {# 截取80个字符并添加... #}
                    <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                    <span>阅读量：{{ item.Views }}</span>
                </a>
            </li>
            {% empty %}
            <li>暂无新闻文章。</li>
            {% endfor %}
        {% endarchiveList %}
    </ul>
</div>

代码解析：

  • moduleId="1"：指定我们要获取的是文章模型下的内容。
  • categoryId="5"：明确指定只获取分类ID为5的文章。
  • order="id desc"：确保按文章ID降序排列，即最新发布的在前。
  • limit="5"：限制只显示最新的5篇文章。
  • {% for item in archives %}：循环遍历获取到的每篇文章。
  • {{ item.Thumb }}：输出文章的缩略图。{% if not item.Thumb %}style="display:none;"{% endif %}是一个小技巧，当没有缩略图时隐藏图片标签。
  • {{ item.Title }}、{{ item.Link }}、{{ item.Description }}、{{ item.Views }}：分别输出文章标题、链接、简介和浏览量。
  • {{ stampToDate(item.CreatedTime, "2006-01-02") }}：CreatedTime是时间戳，我们使用stampToDate标签将其格式化为“年-月-日”的日期格式。
  • {{ item.Description|truncatechars:80 }}：使用过滤器将文章简介截取为80个字符，并自动添加省略号。
  • {% empty %}：如果archives为空（即没有文章），则显示“暂无新闻文章。”。

场景二：在分类列表页展示文章列表并支持分页

在访问一个分类页面时，我们希望展示该分类下的所有文章，并提供分页功能。在这种情况下，通常无需手动指定categoryId，archiveList会智能地识别当前页面的分类ID。

<div class="article-list-container">
    <h1>{% categoryDetail with name="Title" %}</h1> {# 显示当前分类的标题 #}

    <ul class="article-list">
        {% archiveList archives with type="page" moduleId="1" order="id desc" limit="10" %}
            {% for item in archives %}
            <li>
                <a href="{{ item.Link }}">
                    <img src="{{ item.Thumb }}" alt="{{ item.Title }}" {% if not item.Thumb %}style="display:none;"{% endif %}>
                    <h2>{{ item.Title }}</h2>
                    <p>{{ item.Description }}</p>
                    <div class="meta-info">
                        <span>发布于：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                        <span>阅读：{{ item.Views }}</span>
                    </div>
                </a>
            </li>
            {% empty %}
            <li>当前分类暂无文章。</li>
            {% endfor %}
        {% endarchiveList %}
    </ul>

    {# 分页导航 #}
    <div class="pagination-nav">
        {% pagination pages with show="5" %}
            <ul>
                <li {% if pages.FirstPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.FirstPage.Link }}">首页</a></li>
                {% if pages.PrevPage %}<li class="prev"><a href="{{ pages.PrevPage.Link }}">上一页</a></li>{% endif %}
                {% for page_item in pages.Pages %}
                    <li {% if page_item.IsCurrent %}class="active"{% endif %}><a href="{{ page_item.Link }}">{{ page_item.Name }}</a></li>
                {% endfor %}
                {% if pages.NextPage %}<li class="next"><a href="{{ pages.NextPage.Link }}">下一页</a></li>{% endif %}
                <li {% if pages.LastPage.IsCurrent %}class="active"{% endif %}><a href="{{ pages.LastPage.Link }}">末页</a></li>
            </ul>
        {% endpagination %}
    </div>
</div>

代码解析：

  • <h1>{% categoryDetail with name="Title" %}</h1>：使用categoryDetail标签获取并显示当前分类的标题，让用户知道他们正在浏览哪个分类。
  • type="page"：激活分页功能。
  • limit="10"：每页显示10篇文章。
  • {% pagination pages with show="5" %}：这是分页的核心。它会生成一个pages对象，其中包含了分页所需的所有信息（总页数、当前页、首页、末页、上一页、下一页以及中间页码列表）。show="5"表示中间页码最多显示5个。
  • 通过遍历pages.Pages，我们构建了页码链接，并使用IsCurrent属性来判断当前页码，以便添加active样式。

总结与**实践

在AnQiCMS中获取并展示指定分类下的文章列表，主要是围绕archiveList标签展开。通过灵活运用moduleId、categoryId、type、limit和order等参数，您可以轻松实现各种内容展示需求。结合stampToDate进行时间格式化，以及pagination标签实现分页，能够构建出功能完善、用户体验良好的动态内容区域。

几点**实践建议：

  • 明确moduleId和categoryId： 在设计模板时，首先确定您要操作的内容模型ID和分类ID。
  • 注意大小写： AnQiCMS的模板标签和参数是大小写敏感的，务必确保拼写正确。
  • 处理空数据： 使用{% empty %}子句或{% if %}条件来优雅地处理没有文章的情况，避免页面显示空白或报错。
  • 善用过滤器： 页面中展示文章简介时，使用truncatechars或truncatewords等过滤器可以有效控制文本长度，保持页面整洁。
  • 图片处理： 在显示文章缩略图时，判断item.Thumb是否存在可以避免src属性为空导致的浏览器错误或样式问题。

通过这些技巧，您可以充分利用AnQiCMS的模板功能，打造出丰富多样的内容展示页面。

常见问题解答（FAQ）

Q1: 我想在一个页面上显示不同内容模型的文章列表，应该怎么操作？ A1: 您可以通过多次调用archiveList标签，并在每次调用时指定不同的moduleId参数来实现。例如，您可以调用一次`archiveList