在安企CMS的开发和内容管理过程中，我们经常需要获取文档（Archive）的相关信息。其中，archiveFilters 和 archiveParams 是两个与自定义字段紧密相关的API接口，但它们的设计目的和适用场景却有所不同。理解两者的区别，能帮助我们更高效地构建网站功能，提升用户体验。

首先，让我们简单了解一下这两个接口的核心功能。

archiveParams 接口（获取文档参数）主要用于获取某个文档模型的所有自定义字段的定义，或者某个具体文档实例所填充的自定义字段值。当我们请求这个接口时，它会返回一个包含字段名称、字段调用名（field_name）、类型、默认值等信息的列表，甚至可以获取到某个字段的所有可选值（例如，如果是一个多选字段，它会返回一个以换行符分隔的字符串）。其主要目的是为了让开发者了解文档模型的结构，或者在前端展示单个文档的完整属性信息。例如，在一个产品详情页，你可能需要展示产品的“尺寸”、“颜色”、“材质”等所有自定义属性及其对应的值，这时 archiveParams 就非常适合。

而 archiveFilters 接口（获取文档参数筛选条件）则是一个更专注于“筛选”功能的接口。它的设计初衷是为了方便我们在前端页面上构建动态的筛选器。当我们调用 archiveFilters 并传入一个模型ID时，它会返回该模型下所有被标记为“可筛选”的自定义字段，并且每个字段都会附带一个 items 数组。这个 items 数组里包含了该筛选字段所有可能的选项（label），更重要的是，它还可能包含对应选项下的文档数量（total）。想象一下，在一个商品列表页，用户通常会看到“品牌”、“价格区间”、“颜色”等筛选条件，每个条件后面还显示着当前筛选结果下，每个选项对应的商品数量，这正是 archiveFilters 所提供的。

那么，在何种场景下我们应该优先使用 archiveFilters 而非 archiveParams 呢？答案在于你的核心需求是否是为了 构建交互式的文档筛选界面。

当你的目标是为用户提供一个直观、可操作的筛选面板时，archiveFilters 是你更优的选择。它直接提供了筛选器所需的“维度”和“选项”列表。例如，你在开发一个招聘网站，用户希望能够根据“城市”、“学历”、“工作经验”等条件来筛选职位列表。

  1. 动态生成筛选选项：archiveFilters 会返回“城市”字段，其 items 数组中包含了“北京”、“上海”、“广州”等具体的城市选项。这比 archiveParams 返回的一个 value: "北京\n上海\n广州" 这样的原始字符串要方便得多，你无需手动解析字符串，可以直接遍历 items 数组来生成前端的筛选按钮或下拉菜单。
  2. 获取筛选选项下的文档数量：如果 archiveFilters 返回的 items 中 total 字段有实际数值，那么它还能告诉你当前条件下，选择某个选项（如“城市：北京”）会有多少个匹配的文档。这对于用户体验至关重要，用户可以一目了然地知道哪个筛选条件有内容，避免选择空的结果。
  3. 更清晰的用途定义：archiveFilters 明确地告诉我们哪些自定义字段是设计用来作为筛选条件的。这有助于我们专注于构建过滤功能，而不是去猜测哪些 archiveParams 返回的字段可以被用于筛选。

相反，如果你只是想展示某个文档的所有详细信息（包括它的自定义字段值），或者你想在后台工具中查看某个文档模型的完整字段配置，archiveParams 依然是不可替代的。它提供的是每个字段的“属性”本身，而不是为了动态筛选而预处理好的“选项列表”。

总结来说，当你需要为用户提供 可交互、可选择的动态筛选功能，并且希望展示每个筛选选项的匹配数量时，毫无疑问，archiveFilters 是你的首选。它能够帮你高效地构建出功能丰富且用户友好的筛选界面。而 archiveParams 则更侧重于获取文档或模型自定义字段的原始结构和具体内容。

常见问题（FAQ）

  1. archiveFilters 接口返回的 total 字段为什么有时是 0？ total 字段表示当前筛选条件下，该选项所包含的文档数量。如果所有筛选选项的 total 都显示为 0，这通常意味着该模型下还没有任何文档，或者所有文档都不满足当前系统可能存在的默认筛选条件（例如未发布、未审核等）。此外，如果您的项目是新的或者数据量较小，total 值也可能因为没有数据而显示为0。

  2. 我能否将 archiveParams 获取到的自定义字段手动处理后用于筛选？ 理论上是可以的。archiveParams 可以提供自定义字段的 value，例如 value: "北京\n上海\n重庆"。你可以手动解析这个字符串，将其拆分成独立的选项。然而，这样做会增加前端逻辑的复杂度，并且 archiveParams 无法直接提供每个选项对应的文档数量，这将极大地降低筛选界面的用户体验。因此，除非 archiveFilters 无法满足你的特殊需求，否则不建议通过 archiveParams 来构建筛选器。

  3. 如果我的自定义字段没有在 archiveFilters 接口中返回，我该怎么办？ archiveFilters 只会返回在安企CMS后台模型管理中被明确标记为“可筛选”的自定义字段。如果某个你希望用来筛选的字段没有出现在 archiveFilters 的结果中，你需要登录安企CMS后台，进入对应的“文档模型管理”，找到该自定义字段并编辑其属性，确保它被勾选为“可筛选”。保存后，archiveFilters 接口就会返回该字段及其选项。