如何在 AnQiCMS 模板中按分类、模型、推荐属性等条件筛选并显示文档列表？

作为一名资深的AnQiCMS网站运营人员，我深知高效内容管理和灵活展示的重要性。在AnQiCMS中，文档列表的筛选与显示是构建动态网站不可或缺的功能。无论是展示特定分类下的最新文章，还是根据内容模型区分产品和新闻，亦或是突出推荐内容，AnQiCMS强大的模板标签都能帮助我们轻松实现这些需求。

本篇文章将详细阐述如何在AnQiCMS模板中，利用archiveList标签及其丰富的参数，按分类、模型、推荐属性等多种条件筛选并显示文档列表。

archiveList标签：动态内容展示的核心

在AnQiCMS的模板体系中，archiveList标签是用于获取和展示文档列表的核心工具。它提供了多样化的参数，让我们可以根据具体业务需求精确控制要显示的内容。这个标签允许我们不仅获取文档数据，还能对其进行排序、限制数量，甚至进行分页显示。

使用archiveList标签时，通常会像这样定义一个变量来存储获取到的文档列表：{% archiveList archives with ... %}。这里的archives就是我们将要循环遍历的文档集合。

基于分类筛选文档列表

当我们需要展示特定分类下的文档时，categoryId参数便成为了关键。

我们可以通过指定一个或多个分类ID来获取相应的文档。例如，若要获取ID为1的分类下的所有文档，可以这样使用：{% archiveList archives with categoryId="1" type="list" limit="10" %}。如果需要展示多个分类的文档，分类ID之间可以使用逗号分隔，如：categoryId="1,2,3"。

在某些情况下，我们可能希望在分类页面自动显示当前分类的文档。此时，categoryId参数可以省略，archiveList标签会智能地读取当前页面的分类ID来获取文档。如果需要明确地不读取当前分类ID，则可以将categoryId设置为"0"。

此外，archiveList标签还提供了child参数来控制是否包含子分类的文档。默认情况下，child为true，即包含子分类的文档。若只想显示当前分类而不包含其子分类的文档，可以将其设置为child=false。另外，excludeCategoryId参数则允许我们排除特定分类的文档，这在构建一些特殊的内容区域时非常有用。

基于内容模型筛选文档列表

AnQiCMS支持自定义内容模型，例如文章、产品等。moduleId参数允许我们根据文档所属的内容模型来筛选列表。

每个内容模型都有一个唯一的ID。例如，假设文章模型的ID是1，产品模型的ID是2，我们可以通过指定moduleId参数来获取相应模型的文档。要显示所有文章模型的文档列表，我们可以这样编写模板代码：{% archiveList archives with moduleId="1" type="list" limit="10" %}。这使得我们可以轻松地将不同类型的内容展示在网站的不同区域，比如在“新闻中心”只显示文章，在“产品展示”只显示产品。

基于推荐属性（Flag）筛选文档列表

AnQiCMS的文档具有多种推荐属性（Flag），用于标记内容的特殊性质，例如“头条”、“推荐”、“幻灯”等。这些属性在后台添加文档时可以进行设置，并通过特定的字母代码来表示。

要根据推荐属性筛选文档，可以使用flag参数。例如，若要显示所有被标记为“推荐”属性（对应的flag为c）的文档，可以这样实现：{% archiveList archives with flag="c" type="list" limit="5" %}。AnQiCMS支持的推荐属性字母包括：头条[h]、推荐[c]、幻灯[f]、特荐[a]、滚动[s]、加粗[h]、图片[p]、跳转[j]。

与categoryId类似，excludeFlag参数则可以用于排除具有特定推荐属性的文档，这在构建一些不展示特定推荐内容的列表时非常有用。如果需要在文档列表中显示文档的flag标签，则需要将showFlag参数设置为true。

结合多种条件进行筛选与展示

archiveList标签的强大之处在于可以组合使用这些筛选条件，以满足更复杂的业务逻辑。例如，我们可以同时筛选特定分类下、特定内容模型、且具有某种推荐属性的文档。

一个常见的应用场景是：在首页的“精选新闻”区域，显示文章模型下，分类ID为1的“新闻动态”分类中，且被标记为“推荐”的最新5篇文章。这可以通过以下代码实现：

{% archiveList articles with moduleId="1" categoryId="1" flag="c" order="id desc" type="list" limit="5" %}
    {% for item in articles %}
    <li>
        <a href="{{ item.Link }}">{{ item.Title }}</a>
        <span>{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
    </li>
    {% empty %}
    <li>暂无精选新闻。</li>
    {% endfor %}
{% endarchiveList %}

在展示文档列表时，我们通常会使用for循环来遍历archiveList标签返回的文档集合。循环中的每个item都代表一个文档对象，它包含文档的各种字段，如Id、Title、Link、Description、Thumb（缩略图）、Views（浏览量）和CreatedTime（创建时间）等。我们可以根据需要，在循环中调用这些字段来构建丰富多样的展示效果。例如，{{ item.Title }}将显示文档标题，而{{ stampToDate(item.CreatedTime, "2006-01-02") }}则可以将时间戳格式化为可读日期。

排序、数量与列表类型控制

除了筛选条件，archiveList标签还提供了对列表的排序、数量限制和显示类型的精细控制。

order参数允许我们定义文档的排序方式，例如按最新发布id desc、按浏览量views desc、或按后台自定义排序sort desc。

limit参数则控制返回的文档数量。如果我们需要从第N条文档开始获取M条数据，可以使用offset模式，如limit="2,10"表示从第2条开始获取10条数据。

type参数定义了列表的显示类型。type="list"用于获取固定数量的文档，而type="page"则与pagination标签配合使用，实现分页显示。当type="page"时，archiveList会自动处理URL中的分页参数，并在页面上生成对应的分页链接，极大地简化了分页功能的实现。例如，在分类列表页中，使用type="page"结合pagination标签可以轻松构建完整的带分页的文章列表。

文档列表分页的实现

实现分页功能时，archiveList标签的type参数必须设置为page。随后，我们需要使用pagination标签来渲染分页导航。

以下是一个完整的分页列表代码示例，它将展示文章模型下，分类ID为1的文档，并实现每页10条记录的分页：

<div>
    {% archiveList archives with moduleId="1" categoryId="1" type="page" limit="10" %}
        {% for item in archives %}
        <article>
            <h2><a href="{{ item.Link }}">{{ item.Title }}</a></h2>
            <p>{{ item.Description }}</p>
            <footer>
                <span>发布日期: {{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
                <span>浏览量: {{ item.Views }}</span>
            </footer>
        </article>
        {% empty %}
        <p>此分类下暂无文档。</p>
        {% endfor %}
    {% endarchiveList %}

    <nav class="pagination">
        {% pagination pages with show="5" %}
            <ul>
                {% if pages.FirstPage %}
                <li><a href="{{ pages.FirstPage.Link }}">首页</a></li>
                {% endif %}
                {% if pages.PrevPage %}
                <li><a href="{{ pages.PrevPage.Link }}">上一页</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 }}">下一页</a></li>
                {% endif %}
                {% if pages.LastPage %}
                <li><a href="{{ pages.LastPage.Link }}">尾页</a></li>
                {% endif %}
            </ul>
        {% endpagination %}
    </nav>
</div>

通过以上方法，我们可以灵活地在AnQiCMS模板中根据分类、模型、推荐属性等多种条件筛选并显示文档列表，极大地增强了网站内容的动态性和可管理性。

常见问题 (FAQ)

1. 如果archiveList没有找到任何符合条件的文档，如何显示“暂无内容”？ 在{% for ... %}循环的内部，可以添加{% empty %}...{% endfor %}结构。当列表为空时，empty标签内的内容将会被显示。例如：

{% archiveList articles with categoryId="1" type="list" limit="10" %}
    {% for item in articles %}
        {# 显示文档内容 #}
    {% empty %}
        <p>很抱歉，当前没有找到符合条件的文档。</p>
    {% endfor %}
{% endarchiveList %}

2. 我可以在archiveList循环中获取每个文档的自定义字段吗？ 可以。每个item对象默认包含了核心字段。如果需要访问文档模型中定义的自定义字段，可以直接通过item.自定义字段名来访问，前提是该自定义字段在后台设置了且文档填写了对应值。或者，您可以使用archiveParams标签，传入item.Id来获取某个文档的所有自定义参数，然后遍历显示。

{% archiveList articles with moduleId="1" type="list" limit="5" %}
    {% for item in articles %}
    <p>文档标题: {{ item.Title }}</p>
    {% archiveParams params with id=item.Id %}
        {% for param in params %}
        <p>{{ param.Name }}: {{ param.Value }}</p>
        {% endfor %}
    {% endarchiveParams %}
    {% endfor %}
{% endarchiveList %}

3. 如何在列表页面中实现按自定义字段进行筛选的功能？ archiveList标签本身不直接支持在模板中通过参数进行自定义字段的动态筛选。然而