在安企CMS中，当我们需要在网站上动态展示文章、产品或其他文档列表时，archiveList 标签是我们不可或缺的核心工具。它提供了高度的灵活性和强大的功能，无论您是想展示最新内容、热门文章，还是特定分类下的产品，甚至是根据关键词搜索或自定义筛选条件来生成列表，archiveList 都能轻松应对。

archiveList 的核心功能与基本用法

archiveList 标签主要用于从数据库中查询并展示符合特定条件的文档集合。它的基本使用结构通常包括两个部分：archiveList 标签本身用于定义查询条件，以及一个 for 循环用于遍历查询到的每一条文档数据。

一个典型的用法示例如下：

{% archiveList archives with type="list" limit="10" %}
    {% for item in archives %}
        <li><a href="{{ item.Link }}">{{ item.Title }}</a></li>
    {% endfor %}
{% endarchiveList %}

在这个例子中：

  • archiveList 是标签名。
  • archives 是我们自定义的一个变量名，用于存储查询到的文档列表数据。您可以根据自己的喜好将其命名为 articles、products 等。
  • with type="list" limit="10" 是用于指定查询条件的参数。type="list" 表示我们希望获取一个简单的列表，而不是分页列表或相关文档列表；limit="10" 则限制了显示文档的数量为10条。
  • {% for item in archives %} 语句用来遍历 archives 变量中的每一条文档数据。在循环体内，item 变量代表当前正在处理的文档。
  • {{ item.Link }} 和 {{ item.Title }} 则分别用于输出当前文档的链接和标题。

灵活控制文档的获取与展示

archiveList 标签提供了丰富的参数，让我们可以精确地控制要获取哪些文档以及如何排序它们。

  1. 内容定位：指定从何处获取文档

    • moduleId: 如果您的网站有多种内容模型（如文章、产品），可以通过 moduleId="1"（假设文章模型的ID是1）来指定只获取文章模型的文档。
    • categoryId: 想展示某个特定分类下的文档？使用 categoryId="分类ID"。如果需要展示多个分类的文档，可以用逗号分隔多个ID，例如 categoryId="1,2,3"。值得注意的是，如果您不指定 categoryId，它会尝试自动读取当前页面的分类ID，如果您想禁用这个自动行为，可以明确设置为 categoryId="0"。
    • excludeCategoryId: 有时我们可能需要排除某些分类的文档，此时可以使用 excludeCategoryId="要排除的分类ID"。
    • flag, excludeFlag: 安企CMS支持为文档设置多种推荐属性，如 头条[h]、推荐[c]、幻灯[f] 等。通过 flag="c"，您可以轻松调取所有被标记为“推荐”的文档。同样，excludeFlag 参数可以帮助您排除特定属性的文档。
    • child: 默认情况下，categoryId 会包含其子分类下的文档。如果您只想获取指定分类本身的文档，而不包括其子分类，可以设置 child=false。
    • userId, parentId: 针对特定作者发布的文档或具有父子关系的文档，这两个参数也提供了精确的定位功能。
    • siteId: 对于多站点管理的场景，您可以通过 siteId 参数指定要获取哪个站点的数据，实现跨站点的内容调用。

  2. 展示顺序与数量：如何排序和限制条数

    • order: 文档的排序方式非常关键。您可以根据 id 降序 (id desc) 获取最新发布的文档，或者按 views 降序 (views desc) 展示热门内容。如果您在后台设置了自定义排序，order="sort desc" 会按您的设定显示。
    • limit: 这个参数控制了列表显示的文档数量，例如 limit="10" 显示10条。它还支持 offset,limit 的形式，比如 limit="2,10" 表示从第2条文档开始，获取10条数据。

  3. 列表类型：list、page 与 related

    • type="list": 这是最简单的列表模式，按照 limit 参数指定数量，直接显示文档。
    • type="page": 当您需要为文档列表添加分页功能时，就应该使用 type="page"。此时，您还需要结合安企CMS提供的 pagination 标签来构建分页导航，实现例如“上一页”、“下一页”以及页码跳转等功能。
    • type="related": 用于在文档详情页获取相关文档。它会智能地根据当前文档的分类或其他元数据来推荐内容。您还可以通过 like="keywords" 让它根据关键词匹配相关文档，或者 like="relation" 只显示后台手动设置的相关文档。

  4. 高级用法：搜索与自定义筛选

    • q: 当 type="page" 时，q 参数可以用于实现搜索功能。您可以在 archiveList 标签中直接指定 q="搜索关键词"，或者更灵活地，让它自动读取 URL 中的 q 查询参数，从而实现用户在搜索框中输入关键词后的动态搜索结果展示。
    • 筛选参数: 如果您在后台内容模型中为文档定义了额外的可筛选字段（例如房产网站的“户型”、“区域”等），这些筛选条件可以通过 URL 的查询参数传递给 archiveList。结合 archiveFilters 标签，您可以构建出强大的筛选导航。
    • combineId 和 combineFromId: 这是一组非常独特且强大的参数，适用于需要将两篇文档组合展示的场景，例如“从城市A到城市B的旅游线路”。它们允许您在列表中动态地将另一篇文档的内容附加到当前文档上，并在链接中体现这种组合关系。

循环体内可用的文档数据

在 for item in archives 循环中，item 对象包含了当前文档的丰富信息，您可以根据需求调用：

  • 基本信息: {{ item.Id }} (ID), {{ item.Title }} (标题), {{ item.Link }} (链接), {{ item.Description }} (描述), {{ item.Views }} (浏览量) 等。
  • 时间信息: {{ stampToDate(item.CreatedTime, "2006-01-02") }} (发布时间，需要 stampToDate 格式化)。
  • 图片信息: {{ item.Logo }} (封面首图), {{ item.Thumb }} (封面缩略图)。如果文档包含多张图，{{ item.Images }} 会返回一个图片URL数组，您可以在循环中再次遍历展示。
  • 分类信息: {{ item.CategoryId }} (分类ID)。要获取分类名称或链接，通常需要结合 categoryDetail 标签，如 {% categoryDetail with name="Title" id=item.CategoryId %}。
  • **自定义字段