在网站运营中，为用户提供便捷的内容筛选功能，能够显著提升用户体验和内容发现效率。安企CMS提供了强大的接口，让我们能够灵活地获取和利用这些筛选条件。今天，我们就来探讨如何在安企CMS中获取指定文档模型的参数筛选条件列表。

理解筛选条件的重要性

想象一下，如果您的网站上有很多产品或文章，用户想根据“城市”、“学历”或“产品类型”等维度进行查找。如果每次筛选都需要手动输入关键词，效率会很低。通过提供预设的筛选条件列表，用户只需点击或选择，就能快速定位到目标内容。这些动态的筛选条件，正是网站提升互动性和用户友好度的关键。

安企CMS为此提供了一个专门的接口，让我们可以轻松获取这些筛选参数，进而在前端页面上构建出功能丰富的筛选器。

获取筛选条件的核心接口

要获取指定文档模型的参数筛选条件列表，我们需要使用安企CMS的 archive/filters 接口。这个接口是专门为获取模型的筛选字段及其对应的可选项而设计的。

API 调用方式

该接口的调用地址非常直观：

{域名地址}/api/archive/filters

请记住，{域名地址} 需要替换成您实际的网站域名，例如 https://www.anqicms.com/api/archive/filters。

这个接口采用 GET 方法进行调用，这意味着您只需要在请求中附带必要的参数，而不需要在请求体中发送数据。

核心请求参数：moduleId

要获取特定文档模型的筛选条件，最关键的就是提供 moduleId。moduleId 代表了您想要查询的文档模型的唯一标识符。例如，“文章”模型可能有一个 ID（比如 1），“产品”模型可能有另一个 ID（比如 2）。

  • 如何获取 moduleId？ 您可以通过安企CMS后台查看到各个模型的 ID，或者调用 module/list 接口来获取所有模型的列表及其对应的 ID。

当您发起请求时，只需将 moduleId 作为查询参数附加到 URL 后即可。例如，如果您想获取 ID 为 1 的文档模型的筛选条件，请求示例如下：

{域名地址}/api/archive/filters?moduleId=1

接口返回数据的解读

成功调用 archive/filters 接口后，您会得到一个 JSON 格式的响应。这份响应包含了该文档模型下所有可供筛选的字段及其详细信息。让我们来详细解析一下返回的数据结构：

{
  "code": 0,
  "data": [
    {
      "name": "城市",
      "field_name": "city",
      "items": [
        {
          "label": "全部",
          "total": 0
        },
        {
          "label": "北京",
          "total": 0
        },
        {
          "label": "上海",
          "total": 0
        }
      ]
    },
    {
      "name": "学历",
      "field_name": "certificate",
      "items": [
        {
          "label": "全部",
          "total": 0
        },
        {
          "label": "硕士",
          "total": 0
        },
        {
          "label": "本科",
          "total": 0
        }
      ]
    }
  ],
  "msg": ""
}

响应中的 data 字段是一个数组，数组的每个元素都代表一个可筛选的字段。每个筛选字段的结构包含以下几个重要部分：

  • name (string): 这是筛选条件的显示名称，例如“城市”、“学历”。这个名称通常用于前端界面展示给用户。
  • field_name (string): 这是筛选字段的调用名称，例如“city”、“certificate”。这个字段非常重要，因为它是在您之后调用 archive/list 接口进行实际文档列表筛选时，需要作为请求参数的键名。
  • items (object[]): 这是一个数组，包含了当前筛选字段所有可用的参数选项。每个选项又包含：
    • label (string): 参数选项的显示文本，如“北京”、“硕士”、“全部”。
    • total (int): 理论上表示该选项下匹配的文档数量。在当前的文档示例中，它显示为 0，这可能表示该接口在设计上不直接返回筛选条件下的精确计数，或者需要在特定配置下才能生效。在构建前端筛选器时，您主要关注 label 即可。

将筛选条件应用于文档列表

获取到这些筛选条件列表后，您就可以在网站前端动态地生成筛选器了。例如，您可以为“城市”和“学历”创建下拉菜单或复选框组。

当用户在一个筛选器中选择了一个或多个选项时，您就可以使用 field_name 和 label 的值，结合 archive/list 接口来获取匹配的文档列表。

例如，如果用户选择了“城市”为“北京”，您就可以向 archive/list 接口发送类似以下的请求：

{域名地址}/api/archive/list?moduleId=1&city=北京

这里的 city 正是 archive/filters 接口返回的 field_name，而 北京 则是用户选择的 label。通过这种方式，用户可以进行多条件组合筛选，极大地方便了内容的探索。

小贴士

  • 后台配置是基础： 只有在安企CMS后台的文档模型中，将某个自定义字段设置为“可筛选”，它才会在 archive/filters 接口中出现。如果您发现缺少某些筛选条件，请先检查后台的模型字段配置。
  • “全部”选项的处理： items 中通常会包含一个“全部”的 label。当用户选择“全部”时，通常意味着不对该字段进行筛选，所以在调用 archive/list 时，可以省略该 field_name 参数。
  • field_name 的命名规范： field_name 通常是英文或拼音，用于接口调用，而 name 则是中文或其他语言，用于界面显示。

掌握 archive/filters 接口的使用，将让您能够为您的安企CMS网站构建出更加灵活、用户友好的内容筛选功能，有效提升网站的实用性和用户体验。

常见问题 (FAQ)

1. 为什么我调用 archive/filters 接口时返回的 data 数组是空的？ 这通常是因为以下几个原因：

  • 您提供的 moduleId 不正确，或者该 ID 对应的模型下没有配置任何筛选字段。
  • 该文档模型下虽然有自定义字段，但这些字段在安企CMS后台的模型设置中，并没有被勾选为“可筛选”属性。请登录后台，检查对应模型的字段配置。

2. field_name 和 name 有什么区别？我应该用哪个？ name 是给用户界面展示的，例如显示为“城市”、“学历”，它更具可读性。而 field_name 则是用于程序内部识别和接口调用的，例如 city、certificate。当您构建前端筛选器，需要将用户选择的条件发送给 archive/list 接口时，应该使用 field_name 作为请求参数的键。

3. items 里的 total 字段总是显示为 0，这正常吗？它有什么用？ 根据您提供的文档示例，total 字段显示为 0 是正常的。这可能意味着在当前的接口设计中，archive/filters 接口主要用于返回可筛选的选项列表（即 label），而没有实时统计每个选项下的文档数量。在构建前端筛选器时，您主要关注 label 来生成选项即可。如果需要显示每个筛选条件下的文档数量，可能需要单独调用 archive/list 接口并结合不同的筛选条件来统计。