如何使用`archiveList`标签，在安企CMS中灵活构建各种文档列表和分页显示？

在安企CMS中管理和展示内容是核心操作，其中archiveList标签扮演着至关重要的角色。它不仅能帮助我们灵活地呈现文章、产品等各类文档列表，还能与分页功能无缝衔接，满足各种复杂的内容展示需求。

认识archiveList标签：内容展示的利器

archiveList标签是安企CMS模板中用于获取文档列表的核心工具。无论我们想在首页展示最新文章、在分类页显示特定产品，或者在文章详情页推荐相关内容，archiveList都能轻松应对。它的强大之处在于其丰富的参数，允许我们精确控制内容的筛选、排序和展示方式。

archiveList的核心能力与常用参数

使用archiveList的基本语法是{% archiveList 变量名称 with 参数 %}...{% endarchiveList %}。其中，“变量名称”是你为获取到的文档列表自定义的名字，在标签内部可以通过这个名字进行遍历。接下来，我们详细了解一下它的一些常用参数：

  1. 指定内容模型（moduleId） 安企CMS支持灵活的内容模型，如文章、产品等。通过moduleId参数，你可以指定希望获取哪个模型下的文档。例如，moduleId="1"可能代表文章模型，而moduleId="2"可能代表产品模型。这让你可以轻松地在不同页面展示不同类型的内容。

  2. 按分类筛选（categoryId / excludeCategoryId） 如果你希望获取特定分类下的文档，可以使用categoryId参数，支持单个ID或多个ID用逗号分隔。比如，categoryId="1,2,3"会列出ID为1、2、3的分类下的文档。相反，excludeCategoryId则可以帮助你排除某些分类。如果页面本身就处于某个分类下，archiveList默认会读取当前分类ID，如果你不想这样，可以显式设置categoryId="0"。

  3. 控制显示数量与偏移（limit） limit参数用于控制每次调用显示多少条文档。如果你只想获取前10条最新内容，可以设置limit="10"。limit还支持“偏移模式”，比如limit="2,10"表示从第3条内容开始，获取10条数据（跳过前2条）。

  4. 灵活的排序方式（order） 内容的排序方式多种多样，order参数为你提供了多种选择：

    • order="id desc"：按文档ID倒序，通常用于显示最新发布的文档。
    • order="views desc"：按浏览量倒序，用于展示热门内容。
    • order="sort desc"：按后台自定义排序字段倒序。默认情况下，如果不指定order，系统会采用自定义排序。

  5. 利用推荐属性（flag / excludeFlag / showFlag） 安企CMS允许你为文档设置多种推荐属性，如头条[h]、推荐[c]、幻灯[f]等。flag="c"可以筛选出带有“推荐”属性的文档。excludeFlag则用于排除具有特定属性的文档。如果你想在列表项中显示文档的推荐属性，showFlag=true会帮你实现。

  6. 定义列表类型（type） type参数是archiveList的一个关键属性，它决定了标签的工作模式：

    • type="list"：默认模式，只按照limit参数获取指定数量的文档。
    • type="page"：分页模式，常用于列表页，与pagination标签配合使用，实现分页显示。
    • type="related"：相关文档模式，在文档详情页使用，用于获取与当前文档相关的其他文档。它还可以结合like="keywords"（按关键词关联）或like="relation"（按后台手动设置的关联文档）进一步细化关联逻辑。

  7. 搜索关键词（q） 当type="page"时，q参数可以用于实现文档搜索。你可以显式设置q="你的关键词"，或者更智能地，archiveList会自动读取URL中名为q的查询参数作为搜索关键词。

  8. 自定义筛选参数 这是一个高级功能，如果你的内容模型定义了自定义字段并设置为可筛选，那么这些字段可以通过URL查询参数的形式作为筛选条件。例如，如果有一个自定义字段sex，你可以通过url?sex=男来筛选性别为“男”的文档。这通常与archiveFilters标签一起使用，构建复杂的筛选界面。

  9. 多站点数据调用（siteId） 如果你在使用安企CMS的多站点管理功能，并且需要调用其他站点的数据，可以通过siteId参数指定目标站点ID。

  10. 组合文档（combineId / combineFromId） 这是一对非常有意思的参数，用于构建“组合文档”的列表。例如，在旅行网站中，可以组合“北京”和“上海”两篇文档，生成“从北京到上海的旅游线路”这样的标题和链接。combineId用于在当前文档后附加一个文档，combineFromId则用于在前置附加。

实际应用场景：灵活构建内容列表

了解了这些参数，我们来看看如何在实际项目中灵活运用archiveList。

场景一：展示普通文档列表

假设你希望在网站首页展示最新发布的5篇新闻资讯。

{% archiveList latestNews with moduleId="1" limit="5" order="id desc" %}
    {% for item in latestNews %}
        <div class="news-item">
            <a href="{{ item.Link }}">{{ item.Title }}</a>
            <span>发布日期：{{ stampToDate(item.CreatedTime, "2006-01-02") }}</span>
        </div>
    {% endfor %}
{% endarchiveList %}

这里，latestNews是我们的变量名，moduleId="1"假定新闻属于文章模型，limit="5"限制显示5条，order="id desc"确保是最新的。

场景二：构建带分页的文档列表

在分类页或搜索结果页，我们经常需要分页显示大量内容。这时type="page"和pagination标签是**搭档。

{% archiveList archives with type="page" moduleId="1" categoryId="10" limit="10" q=urlParams.q %}
    {% for item in archives %}
        <div class="article-summary">
            <a href="{{ item.Link }}">
                <h3>{{ item.Title }}</h3>
                {% if item.Thumb %}<img src="{{ item.Thumb }}" alt="{{ item.Title }}">{% endif %}
                <p>{{ item.Description|truncatechars:100 }}</p>
            </a>
            <small>发布于 {{ stampToDate(item.CreatedTime, "2006-01-02") }} | 浏览量：{{ item.Views }}</small>
        </div>
    {% empty %}
        <p>抱歉，当前分类下没有找到任何内容。</p>
    {% endfor %}

    {# 分页代码 #}
    <div class="pagination-container">
        {% pagination pages with show="5" %}
            <a class="first-page {% if pages.FirstPage.IsCurrent %}active{% endif %}" href="{{ pages.FirstPage.Link }}">首页</a>
            {% if pages.PrevPage %}<a class="prev-page" href="{{ pages.PrevPage.Link }}">上一页</a>{% endif %}
            {% for pageItem in pages.Pages %}
                <a class="page-number {% if pageItem.IsCurrent %}active{% endif %}" href="{{ pageItem.Link }}">{{ pageItem.Name }}</a>
            {% endfor %}
            {% if pages.NextPage %}<a class="next-page" href="{{ pages.NextPage.Link }}">下一页</a>{% endif %}
            <a class="last-page {% if pages.LastPage.IsCurrent %}active{% endif %}" href="{{ pages.LastPage.Link }}">尾页</a>
        {% endpagination %}
    </div>
{% endarchiveList %}

这个例子中，type="page"开启分页模式，categoryId="10"限定分类，limit="10"表示每页10条。q=urlParams.q则会自动读取URL中的搜索关键词。pagination标签紧随其后，利用pages变量（由archiveList在type="page"时自动提供）来构建完整的页码导航。show="5"表示最多显示5个中间页码按钮。

场景三：展示相关文档

在文章详情页，我们通常会推荐一些相关内容，提高用户粘性。

{% archiveList relatedArticles with type="related" limit="6" %}
    {% if relatedArticles %}
    <h4>相关推荐</h4>
    <ul class="related-list">
        {% for item in relatedArticles %}
            <li><a href="{{ item.Link }}">{{ item.Title }}</a></li>
        {% endfor %}
    </ul>
    {% endif %}
{% endarchiveList %}

这里type="related"让系统自动根据当前文档找到相关内容，limit="6"限制数量。如果需要更精细的控制，可以添加like="keywords"或like="relation"参数。

场景四：多分类、多模型混合展示

有时，你可能需要在同一页面循环多个分类，并在每个分类下显示其文档。

{% categoryList categories with moduleId="1" parentId="0" %}
    {% for category in categories %}
        <section>
            <h2><a href="{{ category.Link }}">{{ category.Title }}</a></h2>
            <ul>
                {% archiveList articlesInCategory with type="list" categoryId=category.Id limit="5" %}
                    {% for article in articlesInCategory %}
                        <li><a href="{{ article.Link }}">{{ article.Title }}</a></li>
                    {% empty %}
                        <li>该分类暂无文章。</li>
                    {% endfor %}
                {% endarchiveList %}
            </ul>
        </section>
    {% endfor %}
{% endcategoryList %}

此例中，我们先用categoryList获取顶级分类，然后在循环中对每个分类使用archiveList来获取其下的文章。

archiveList返回的数据结构（item）

在archiveList标签内部，通过for item in 变量名称循环时，item对象包含了文档的丰富信息，你可以直接通过{{ item.字段名 }}的方式调用，例如：

  • item.Id：文档ID
  • item.Title：文档标题
  • item.Link：文档链接
  • item.Description：文档描述
  • item.Thumb：文档缩略图地址
  • item.CreatedTime：文档创建时间戳（需要用stampToDate过滤器格式化）
  • item.Views：文档浏览量
  • item.Flag：文档推荐属性（需showFlag=true）
  • 以及所有在后台内容模型中自定义的字段，例如item.Author、item.Price等。

小结

archiveList标签是安企CMS内容运营和模板开发的基石之一。通过熟练掌握它的各项参数和灵活运用场景，你可以轻松构建出功能强大、用户体验良好的各类内容展示页面。结合pagination等辅助标签，无论是简单的列表还是复杂的筛选分页，都能高效实现。

常见问题 (FAQ)

Q1: archiveList和categoryList标签有什么区别？我该如何选择？ A1: archiveList主要用于获取文档（如文章、产品）的列表，它的结果是具体的文档项。而categoryList则用于获取分类的列表，它的结果是分类项。 选择的关键在于你想展示什么：

  • 如果你想显示“最新文章”、“热门产品”或者“某个分类下的具体文章列表”，就使用archiveList。
  • 如果你想显示“所有产品分类”、“新闻分类列表”或者“带有子分类的导航菜单”，就使用categoryList。 两者经常结合使用，例如在一个分类列表的循环中，嵌套一个archiveList来显示该分类下的文档，就像文章中的场景四示例。

Q2: 我在内容模型中自定义了一些字段，比如“作者（author）”和“来源（source）”，如何在archiveList中显示它们？ A2: 当你通过archiveList获取文档列表后，每个item对象都会自动包含你在内容模型中自定义的字段。你可以像调用内置字段一样直接使用它们。例如，如果你自定义了author字段，在循环中可以直接通过{{ item.Author }}来显示作者信息。

Q3: 我的archiveList设置了type="page"，但分页导航（pagination）没有显示或者显示不正确，可能是什么原因？ A3: 出现这种情况，通常有以下几个原因：

  1. 忘记调用pagination标签： archiveList设置type="page"后，只会准备分页数据，你需要单独在{% endarchiveList %}之后调用{% pagination pages with show="5" %}...{% endpagination %}来渲染分页导航。
  2. pages变量未正确传递： 确保pagination标签使用的变量名与archiveList（当type="page"时）内部自动生成的pages变量一致。
  3. 列表内容不足一页：