在使用安企CMS（AnQiCMS）构建网站时，我们经常会有这样的疑问：除了能够精确地获取某个特定文档的详细信息，系统是否也提供了一次性获取某个分类下或某个模型下所有文档列表的功能？答案是肯定的。安企CMS充分考虑了内容管理和展示的灵活性，提供了功能强大的接口来满足这类需求。

要获取特定分类或模型下的文档列表，主要依赖于安企CMS提供的 /api/archive/list 接口。这个接口是您内容列表展示的核心工具，它不仅能够按分类和模型筛选，还支持丰富的查询和排序功能。

核心功能解析：如何获取文档列表

/api/archive/list 接口让您能够灵活地定义想要获取的文档范围。以下是它的一些关键参数和用法：

  1. 按模型或分类筛选：

    • 模型ID（moduleId）：如果您需要获取特定模型（例如“文章”模型、“产品”模型）下的所有文档，只需传递相应的 moduleId 即可。这对于构建不同类型的内容列表（如产品展示页、博客列表页）非常有用。
    • 分类ID（categoryId）：要获取某个特定分类下的文档，可以使用 categoryId 参数。更棒的是，它支持传入多个分类ID，用逗号隔开，这意味着您可以一次性获取来自多个分类的文档内容。例如，您想同时展示“新闻动态”和“行业资讯”两个分类的文章，就可以通过 categoryId="1,2" 这样的方式来实现。

  2. 包含子分类文档（child）： 默认情况下，当您指定一个分类ID时，该接口通常会包含其所有子分类下的文档。但如果您的需求是只获取当前分类的文档，而不包括其子分类的内容，可以通过设置 child=false 来精确控制。

  3. 分页与数量控制（page, limit）： 为了更好地管理数据量和实现分页加载，archive/list 接口提供了 page 和 limit 参数。

    • 当 type="page" 时，您可以指定 page 参数来获取第几页的内容，同时系统会返回总文档数量（total），这对于构建分页导航至关重要。
    • limit 参数则用于控制每页或每次请求返回的文档数量。它甚至支持偏移量模式，例如 limit="2,10" 表示从第2条开始，获取10条数据，这在一些特殊的数据截取场景下非常实用。

  4. 排序（order）： 内容的呈现顺序同样重要。您可以通过 order 参数指定排序方式，例如 order="created_time desc" 可以获取最新的文档，order="views desc" 则可以按浏览量从高到低排列。支持的字段包括 id、views、category_id、created_time、updated_time 等。

  5. 特色内容筛选（flag）： 安企CMS中的文档可以标记不同的推荐属性（如头条[h]、推荐[c]、幻灯[f]等）。如果您希望只展示具有特定属性的文档，可以使用 flag 参数进行筛选。比如，flag="c" 将仅显示被标记为“推荐”的文档。

  6. 关键词搜索（q）和自定义筛选： 在 type="page" 模式下，您还可以通过 q 参数进行关键词搜索，匹配文档标题中包含特定词语的内容。此外，如果您的文档模型中设置了可筛选的自定义字段，这些字段也能作为查询参数，实现更细致的内容筛选。例如，如果有一个自定义字段 gender，您可以直接通过 gender=男 来筛选出所有性别为“男”的文档。

如何获取必要的ID？

为了使用 /api/archive/list 接口中的 moduleId 和 categoryId 参数，您可能需要先获取这些ID。安企CMS也提供了相应的接口：

  • 获取分类列表：通过 /api/category/list 接口，您可以获取到所有分类或指定模型下的分类列表，从而找到您需要的 categoryId。
  • 获取模型列表：通过 /api/module/list 接口，您可以获取到系统中定义的所有内容模型，进而得到相应的 moduleId。
  • 获取文档筛选条件：如果您想知道某个模型支持哪些自定义筛选条件，可以使用 /api/archive/filters 接口，它会列出指定模型可用的筛选字段及其选项。

综合来看，安企CMS提供了一套完善的API，让您不仅能够获取单个文档的详细内容，更能以极其灵活和强大的方式，根据分类、模型、推荐属性、关键词甚至自定义字段来组织和展示文档列表。无论是搭建博客的文章列表、产品展示页、新闻中心，还是实现复杂的筛选功能，这些接口都能提供坚实的支持。

常见问题 (FAQ)

1. 我能否同时获取多个分类下的文档列表？

当然可以。在调用 /api/archive/list 接口时，categoryId 参数支持传入一个逗号分隔的字符串，例如 categoryId="1,5,9"，这样您就能一次性获取到这三个分类下的所有文档。

2. 如何查询某个模型下自定义字段的筛选选项？

如果您不确定某个内容模型有哪些自定义字段可以用于筛选，可以使用 /api/archive/filters 接口。只需传入该模型的 moduleId，系统就会返回所有可筛选的自定义字段及其对应的选项列表，让您能够构建准确的筛选查询。

3. 我想获取最新发布的10篇文章，应该怎么设置参数？

要获取最新发布的10篇文章，您可以使用 /api/archive/list 接口，并结合 order 和 limit 参数。具体设置可以是 order="created_time desc" 来按发布时间倒序排列，然后设置 limit="10" 来限制返回的文章数量为10篇。