在使用安企CMS（AnQiCMS）进行网站内容管理时，我们常常需要与文档相关的API接口打交道。其中，archiveParams 和 archiveFilters 这两个接口名称乍听之下有些相似，都与“文档参数”有关，但它们在实际应用中有着截然不同的功能和使用场景。理解它们之间的区别，能帮助我们更高效地开发和管理网站。

深入理解 archiveParams 接口：获取特定文档的详细参数

想象一下，你正在浏览一个商品详情页，除了商品标题、描述和图片等基本信息，你还想看到诸如“品牌”、“材质”、“适用人群”这些由后台自定义的附加信息。这时，archiveParams 接口就派上用场了。

archiveParams 接口的目的是获取某个具体文档（archive）所设置的自定义参数的实际值。它需要你提供一个文档的唯一标识，通常是文档ID (id)。当你调用这个接口并指定某个文档时，它会返回该文档所有自定义字段的名称、实际填写的值以及默认值。

例如，如果你的文章模型中自定义了“作者”和“城市”这两个字段，当你获取一篇ID为123的文章的archiveParams时，你可能会得到这样的信息：

  • “作者”字段，它的值是“安企CMS团队”
  • “城市”字段，它的值是“北京”

这里的“作者”和“城市”就是你在文章编辑时为这篇特定文章填入的自定义内容。这个接口通常用于在前端展示单个文档的详细信息时，补充那些非标准字段的内容。你可以选择以有序数组（sorted=true）或无序对象（sorted=false）的形式获取这些参数，以便在模板中灵活遍历或直接访问。

简单来说，archiveParams 就像是查看一本书的“扉页”，告诉你这本特定的书有哪些特色信息。

深入理解 archiveFilters 接口：获取文档模块的筛选条件

而 archiveFilters 接口则承担了完全不同的职责。它并非关注某个具体文档的参数值，而是为某个文档模型（module）提供可用的筛选条件列表。设想你正在一个电商网站的商品列表页，左侧通常会有“按品牌筛选”、“按价格区间筛选”、“按颜色筛选”等选项。这些筛选条件本身，就是通过 archiveFilters 接口获取的。

archiveFilters 接口需要你指定一个模型ID (moduleId)。它会返回该模型下所有被标记为可筛选的自定义字段，以及这些字段可能包含的选项列表。例如，如果你有一个“职位招聘”的模型，其中定义了“城市”和“学历”为可筛选字段，那么调用 archiveFilters 并传入该模型的ID，你将得到：

  • 一个名为“城市”的筛选器，包含“北京”、“上海”、“重庆”等选项。
  • 一个名为“学历”的筛选器，包含“硕士”、“本科”、“大专”等选项。

这些返回的“城市”和“学历”及其选项，并不是某一篇招聘文档的具体内容，而是你可以在整个“职位招聘”模块中，用来过滤文档列表的通用条件。前端开发人员会利用这些信息来动态构建筛选菜单，用户点击这些选项后，再结合 archiveList 接口去请求符合条件的文档列表。

通俗地讲，archiveFilters 就像是图书馆的“分类标签系统”，告诉你图书馆里所有的书可以按哪些分类、哪些主题进行检索。

核心区别总结

  • 关注对象不同： archiveParams 关注单个文档的自定义信息；archiveFilters 关注某个文档模型下所有文档的筛选条件。
  • 返回内容不同： archiveParams 返回的是特定文档的实际参数值；archiveFilters 返回的是文档模型中可用于筛选的字段定义和选项列表。
  • 应用场景不同： archiveParams 通常用于文档详情页展示；archiveFilters 通常用于文档列表页构建筛选器或搜索界面。
  • 请求参数不同： archiveParams 依赖 id 或 filename 定位具体文档；archiveFilters 依赖 moduleId 定位文档模型。

理解了这两者之间的界限，您就能更清晰地规划安企CMS的前后端交互逻辑，无论是展示详尽的文档内容，还是构建灵活的筛选功能，都能游刃有余。

常见问题 (FAQ)

1. archiveParams 接口可以用来筛选文档列表吗？ 不可以。archiveParams 接口的设计初衷是获取单个文档的详细自定义参数，它不具备筛选多篇文档的功能。如果你需要根据自定义字段的值来筛选文档列表，应该使用 archiveList 接口，并配合其支持的自定义筛选参数。archiveFilters 接口则能告诉你 archiveList 接口支持哪些自定义筛选参数及其可选值。

2. 为什么 archiveFilters 接口返回的筛选选项中，total 字段的值都是 0？ 在您提供的文档示例中，total 字段显示为 0，这通常表示该接口在返回筛选条件结构时，并没有实时统计每个筛选选项下有多少篇文档。实际在项目中使用时，前端可能会在获取到这些筛选条件后，再通过调用 archiveList 接口（通常会传入 type=page 并设置 limit 为 0 或 1）来统计每个筛选条件下匹配的文档数量，从而在筛选器旁边显示“（50）”这类数字。

3. 如何才能知道一个自定义字段是否可以被 archiveFilters 接口获取到？ 自定义字段是否可以被 archiveFilters 接口获取到，取决于该字段在安企CMS后台的模型设置中是否被标记为“可筛选”。只有被设置为“可筛选”的字段，才会在 archiveFilters 的结果中出现，作为用户在前端进行过滤操作的选项。