在安企CMS中，实现文档的动态筛选功能是提升网站用户体验的关键一步。这通常涉及到两个核心接口的紧密协作：archiveFilters 用于获取可供筛选的条件，而 archiveList 则负责根据这些条件检索并展示相应的文档列表。深入理解它们如何协同工作，能够帮助我们为网站构建出灵活且用户友好的内容筛选机制。

理解筛选机制：从定义到发现

想象一下，你的网站上发布了大量的文章、产品或其他内容，用户可能希望根据诸如“城市”、“学历”、“产品类别”等自定义属性来查找他们感兴趣的信息。安企CMS的设计哲学之一，就是允许你为不同的内容模型（例如文章模型、产品模型）定义各种自定义字段。更棒的是，你可以将这些自定义字段设置为“可筛选”，这样它们就能作为用户进行内容过滤的依据。

为了让前端应用知道有哪些筛选条件可用，安企CMS提供了archiveFilters 接口。这个接口扮演着“筛选条件发现者”的角色。

当你调用 archiveFilters 接口时，需要向它提供一个 moduleId，明确你想要获取哪个内容模型的筛选条件。例如，如果你有一个ID为1的产品模型，你想获取该模型下所有产品的筛选条件，就传入 moduleId=1。

接口的返回数据中，你会看到一个列表，每个列表项代表一个可筛选的维度。其中：

  • name：这是筛选条件的中文名称，方便用户理解，比如“城市”或“学历”。
  • field_name：这是这个筛选条件在系统内部的字段名称（例如 city 或 certificate），它在后续应用筛选时会作为参数名使用，非常关键。
  • items：这是一个包含具体筛选选项的列表，每个选项都有一个 label（比如“北京”、“上海”）供用户选择。

通过 archiveFilters，你的前端应用就能动态地获取到当前内容模型下所有可用的筛选类别和它们的具体选项，从而灵活地渲染出筛选菜单，比如下拉框、复选框或标签云。

应用筛选条件：将发现转化为过滤

一旦你的前端页面通过 archiveFilters 接口成功获取并展示了所有可用的筛选条件和选项，用户便可以在这些选项中进行选择。接下来，就需要将用户的选择应用到文档列表中，这就轮到archiveList 接口登场了。

archiveList 接口是安企CMS用于获取文档列表的强大工具。它支持多种参数来控制文档的检索，包括按分类ID、关键词、排序方式等。而对于我们这里讨论的自定义筛选，archiveList 提供了一个名为“自定义筛选参数”的灵活机制。

这里的核心操作在于，你需要将archiveFilters 接口返回的 field_name（例如 city）作为参数的键（key），并将用户从 items 中选定的 label 值（例如“北京”）作为参数的值（value），以 key=value 的形式添加到 archiveList 的请求中。

例如，如果用户在前端页面选择了“城市”为“北京”，那么在构建 archiveList 的请求时，你就需要在URL查询参数中加入 city=北京。如果用户还选择了“学历”为“本科”，那么请求参数就会变成 city=北京&certificate=本科。

同时，在调用 archiveList 接口进行筛选时，建议将 type 参数设置为 page。这样做不仅能让你获取到分页所需的总文档数量，还能确保自定义筛选参数能够正确生效。

实际应用场景与操作步骤

在实际的项目开发中，这一流程通常是这样运作的：

  1. 初始化页面加载： 当用户首次访问列表页时，前端首先调用 archiveFilters 接口，传入当前列表页对应的 moduleId。
  2. 动态渲染筛选器： 根据 archiveFilters 返回的数据，前端将“城市”、“学历”等筛选维度及其选项动态地呈现在页面上，可能是一个侧边栏的筛选菜单，或者页面顶部的筛选条。
  3. 用户选择筛选条件： 用户在页面上点击或选择一个或多个筛选选项。
  4. 构建 archiveList 请求： 前端捕获用户的选择，根据 field_name 和 label 构造新的URL查询参数。例如，如果用户选择了“北京”和“本科”，则请求参数可能变为 ?moduleId=1&type=page&page=1&limit=10&city=北京&certificate=本科。
  5. 发送请求并更新列表： 前端使用这些参数调用 archiveList 接口。后端收到请求后，会根据 moduleId、type、page、limit 以及我们传入的自定义筛选参数（如 city 和 certificate）来过滤文档，并返回符合条件的文档列表和总数。
  6. 展示过滤结果： 前端接收到新的数据后，更新页面上的文档列表，同时可能更新筛选条件旁边的文档计数（如果需要）。

通过这种方式，安企CMS的 archiveFilters 和 archiveList 接口协同工作，为网站内容提供了强大而灵活的动态筛选能力，极大地提升了用户浏览和查找信息的效率。

常见问题 (FAQ)

Q1: 为什么我调用 archiveFilters 接口时，返回的 data 数组是空的，或者只有很少的筛选条件？ A1: 这通常有几个原因。首先，请确保你传入的 moduleId 是正确的，并且对应的内容模型确实在安企CMS后台配置了自定义字段。其次，最重要的是，你需要在内容模型的自定义字段设置中，将那些你希望作为筛选条件的字段明确地勾选为“可筛选”。如果字段未设置为可筛选，archiveFilters 接口就不会返回它们。

Q2: 我能同时应用多个筛选条件吗？比如既要“城市”是“北京”的文档，又要“学历”是“本科”的文档？ A2: 完全可以。安企CMS的 archiveList 接口支持接收多个自定义筛选参数。你只需要将不同的 field_name=label 键值对作为独立的查询参数添加到请求URL中即可。例如：/api/archive/list?moduleId=1&type=page&city=北京&certificate=本科。

Q3: archiveFilters 接口返回的 items 列表中的 total 字段有什么用？为什么它在示例中总是0？ A3: items 列表中的 total 字段在设计上是为了表示该筛选选项下当前有多少文档符合条件。然而，在 archiveFilters 接口的默认实现中，它主要负责提供*可用的*筛选选项本身，并不实时统计每个选项下的文档数量，所以通常默认为0。如果你需要在前端显示每个筛选选项对应的文档数量（例如“北京 (123)”、“上海 (45)”），你可能需要在前端单独进行统计，或者考虑通过后端定制开发来提供这些聚合数据。