作为一名资深的网站运营专家，同时深度熟悉安企CMS，我非常理解在构建网站时，如何高效地获取和展示内容是核心所在。今天，我们就来深入探讨安企CMS模板中一个极其重要且功能强大的标签——archiveList，它能帮助我们灵活地获取各类文档列表，为网站内容呈现提供无限可能。

核心功能概览：archiveList 的作用

在安企CMS中，archiveList标签是内容展示的基石。它不仅仅是一个简单的文档列表获取工具，更是一个多功能的“内容调度器”。通过它，我们可以轻松地从数据库中筛选、排序并呈现各种类型的文档，无论是常规的文章列表、特定分类下的产品展示，还是与当前内容相关的推荐文章，甚至需要分页展示的大量内容，archiveList都能游刃有余地应对。

想象一下，您的网站上有一个“最新资讯”版块，需要展示最新的十篇文章；或者在产品详情页下方，需要推荐几款“相关产品”；又或者在某个分类页面，要将该分类下的所有文章以分页形式呈现。这些动态内容的获取和展示，都离不开archiveList的精妙运用。

基本语法与入门：如何调用 archiveList

archiveList标签的使用遵循安企CMS模板引擎的统一风格，即以{% %}包裹，并通过with关键字传递参数。其基本结构简洁明了：

{% archiveList 变量名称 with 参数 %}
    {% for item in 变量名称 %}
        {# 在这里展示文档内容 #}
    {% empty %}
        {# 如果没有内容，显示此段落 #}
    {% endfor %}
{% endarchiveList %}

在这里，变量名称是一个您自定义的变量，例如archives或articles。archiveList标签会将获取到的文档列表存储到这个变量中，随后您就可以在for循环中遍历这个变量，逐一展示每一篇文档的详细信息。{% empty %}子句是一个非常贴心的设计，当列表为空时，它能优雅地显示一段提示信息，而不是让页面显得空荡荡的。

深入理解：archiveList 的常用参数

archiveList标签之所以强大，在于其丰富的参数选项。通过组合这些参数，您可以精确地控制所要获取的文档范围和呈现方式。让我们逐一了解几个核心参数：

  1. 定位内容范围：moduleId 与 categoryId

    • moduleId：指定您希望获取哪个内容模型的文档。例如，moduleId="1"可能代表文章模型，而moduleId="2"可能代表产品模型。这让您可以轻松地在不同类型的内容之间切换。
    • categoryId：如果您只想获取特定分类下的文档，就可以使用这个参数。例如，categoryId="5"会获取ID为5的分类下的所有文档。如果您需要获取多个分类的文档，可以用逗号分隔，如categoryId="1,2,3"。值得一提的是，如果设置为categoryId="0"或完全省略此参数，archiveList会尝试获取当前页面分类或所有分类的文档，这取决于其他参数的配合。
    • excludeCategoryId：与categoryId相反，用于排除指定分类的文档。
    • parentId：当您希望获取某个父级文档下的子级文档时使用，这在构建如项目案例、多步骤教程等有层级关系的内容时非常有用。

  2. 筛选内容属性：flag 与 excludeFlag 安企CMS支持为文档设置多种推荐属性（如头条[h]、推荐[c]、幻灯[f]等）。

    • flag：通过flag="c"，您可以只获取被标记为“推荐”的文档。
    • excludeFlag：用于排除带有特定属性的文档，例如excludeFlag="h"将不显示头条文章。
    • showFlag：如果需要列表中的文档显示其旗标属性，请设置为showFlag=true。

  3. 排序与限制：order 与 limit

    • order：决定文档的排序方式。常见的值包括：id desc（按ID倒序，通常是最新发布）、views desc（按浏览量倒序，热门文章）、sort desc（按后台自定义排序）。您可以根据需求选择最合适的排序方式。
    • limit：控制返回文档的数量。limit="10"将只获取10条文档。它还支持offset模式，如limit="2,10"表示从第2条开始获取10条数据，非常适合跳过前几条内容进行展示。

  4. 展示模式：type type参数是archiveList的核心之一，它定义了文档列表的呈现类型：

    • type="list"：默认模式，只获取指定数量的文档，不涉及分页。适用于侧边栏、推荐列表等。
    • type="page"：分页模式。当您需要将大量文档分多页显示时，必须使用此类型。它会配合pagination标签生成分页链接。
    • type="related"：相关文档模式。通常用于详情页，根据当前文档的类别、关键词或后台设置，智能推荐相关内容。

  5. 动态搜索与过滤：q 与自定义筛选参数

    • q：用于实现搜索功能。例如，q="关键词"将只显示标题中包含该关键词的文档。当type="page"时，archiveList会自动读取URL中的q参数进行搜索。
    • 自定义筛选参数：如果您在后台内容模型中定义了可筛选的字段（如“性别”、“地区”），这些字段可以通过URL参数传递给archiveList进行高级筛选，例如sex=男。

  6. 多站点与组合文档：siteId、combineId 与 combineFromId

    • siteId：如果您启用了多站点功能，可以通过siteId指定从哪个站点获取文档。
    • combineId / combineFromId：这是安企CMS一个非常独特且强大的功能，用于实现文档的“组合对比”。例如，在旅游线路网站上，您可以将“北京”和“上海”的旅游信息组合成“从北京到上海的旅游线路”，并在模板中获取这两个文档的数据进行对比展示。

数据访问：archiveList 循环中的可用字段

一旦archiveList将数据填充到您的自定义变量（例如archives）中，您就可以在for循环中通过item变量访问每篇文档的各种属性。常用的字段包括：

  • item.Id：文档ID。
  • item.Title：文档标题。
  • item.Link：文档链接。
  • item.Description：文档简介。
  • item.Logo：文档封面首图（通常是缩略图的大图）。
  • item.Thumb：文档封面缩略图。
  • item.Views：文档浏览量。
  • item.CreatedTime：文档创建时间（时间戳，需要配合stampToDate过滤器格式化）。
  • item.UpdatedTime：文档更新时间（时间戳，同样需要格式化）。
  • item.CategoryId：文档所属分类ID。
  • 以及所有在内容模型中自定义的字段，您可以直接通过item.自定义字段名来访问。

时间格式化提示：由于CreatedTime和UpdatedTime是时间戳，您需要使用stampToDate过滤器将其转换为可读的日期格式，例如{{stampToDate(item.CreatedTime, "2006-01-02 15:04")}}。

实用场景与示例

为了让您更好地理解archiveList的实际应用，我们