在现代网站设计中，内容筛选功能已经成为提升用户体验和内容可发现性的重要组成部分。一个设计良好的筛选器能够帮助用户快速定位到他们感兴趣的信息，无论是产品、文章还是其他任何形式的内容。对于安企CMS而言，其提供的筛选条件API（/api/archive/filters）是构建这类前端筛选功能的基石。特别是响应数据中的items数组，它是理解并实现动态筛选的关键。

筛选条件的基石：archive/filters API

安企CMS的archive/filters接口，其核心作用是为前端提供指定内容模型下所有可用的筛选条件。当您需要为某个模块（例如文章模块、产品模块）构建筛选器时，只需调用这个API，并传入相应的moduleId。例如，GET /api/archive/filters?moduleId=1 就会返回文章模块的所有筛选器配置。

这个API的响应数据结构清晰，其中最外层的data是一个数组，数组中的每个对象都代表一个独立的筛选器。每一个筛选器对象都包含三个关键属性：name、field_name和items。

  • name：这是筛选器在用户界面上显示的名称，比如“城市”或“学历”，方便用户理解。
  • field_name：这个属性至关重要，它代表了在实际进行内容查询时，需要作为URL参数使用的字段名称。例如，如果name是“城市”，那么field_name可能就是city。
  • items：这便是我们今天的重点，它是一个数组，包含了当前筛选器下所有可供选择的具体项。

深度解读 items 数组

items数组是每个筛选器内部的具体选项集合。数组中的每一个元素又是一个独立的对象，通常包含label和total这两个属性，它们共同构成了前端筛选器每个选项的完整信息。

  • label：筛选选项的显示文本 label属性的值是用户在前端界面上直接看到的选项名称。例如，在一个“城市”筛选器中，items数组中的label可能是“北京”、“上海”、“重庆”等。它是筛选器选项的友好名称，直接呈现给用户。在构建前端界面时，您会使用这些label来创建下拉菜单、复选框、单选按钮或标签云等形式的筛选控件。

  • total：当前选项下的内容数量 total属性则表示在当前筛选选项（即label）下，安企CMS中匹配到的文档总数。这个数字在前端界面中具有极高的实用价值。例如，您可以将“北京 (123)”这样展示给用户，直观地告诉他们选择“北京”这个条件后，会找到123篇相关内容。

    更进一步，total值还可以帮助您优化用户体验：

    • 智能禁用/隐藏： 如果某个选项的total为0，说明当前数据库中没有内容符合该条件，您可以在前端将这个选项置灰（禁用）或直接隐藏，避免用户点击后发现没有内容而感到困惑。
    • 视觉反馈： 数字的存在能给用户提供一种预期，让他们在点击之前就对可能获得的结果数量有所了解。

构建前端筛选器的实践步骤

理解了items数组的结构后，我们就可以着手将其应用于前端筛选器的构建：

  1. 获取筛选数据： 首先，在页面加载时，通过异步请求调用 /api/archive/filters 接口，并携带相应的 moduleId。这将获取到该模块所有可用的筛选条件及其items数组。
  2. 解析与渲染： 接收到响应数据后，遍历data数组。对于每个筛选器对象，提取其name作为筛选器的标题，提取field_name作为后续查询的参数名。接着，遍历其内部的items数组，使用每个item的label渲染出前端的筛选选项（例如，创建一系列的按钮或下拉菜单项）。同时，可以利用total值在label旁显示文档数量，或根据total是否为0来决定选项的可用状态。
  3. 构建查询参数： 当用户在前端选择了一个或多个筛选选项时，您需要根据他们的选择来动态构造查询参数。例如，如果用户在field_name为city的筛选器中选择了label为“北京”的选项，那么您需要将city=北京这个参数加入到您的内容列表API请求中。如果安企CMS支持多选，那么多个选择值通常会用逗号分隔（如city=北京,上海），具体请参考/api/archive/list接口中自定义筛选参数的说明。
  4. 发起内容列表请求： 将构造好的筛选参数，连同分页、排序等其他参数，一并发送给 /api/archive/list 接口。该接口会返回符合所有筛选条件的文档列表，供前端展示。
  5. 更新筛选器状态（可选）： 在某些复杂的筛选场景中，当用户选择了一个筛选条件后，您可能需要再次调用archive/filters接口