当您在使用AnQiCMS构建网站并需要从后端获取文档内容时，会经常接触到文档列表接口（/api/archive/list）。这个接口提供了一个非常重要的 type 参数，它决定了您将以何种方式获取和处理文档列表数据。深入理解 type="page" 和 type="list" 这两种模式的核心区别，对于提升网站性能、优化用户体验以及更灵活地开发功能都至关重要。
type=“list” 模式：高效获取小规模数据
type="list" 模式是文档列表接口的默认行为。它的设计理念在于快速、轻量地获取固定数量的文档内容，而不关注数据的总规模。当您只需要在网站的某个区块，比如首页的“最新发布”、侧边栏的“热门推荐”或文章详情页的“相关文章”中展示少量精选内容时，这个模式就显得非常高效。
在这种模式下，您可以利用 limit 参数来精确控制返回的文档条数，例如 limit="5" 会返回最新的 5 篇文章。值得一提的是，limit 还支持一种“偏移”的用法，比如 limit="2,10"，这意味着您希望跳过前两条记录，然后从第三条记录开始获取接下来的 10 条文档。这种机制在某些特定展示场景下非常灵活。
然而，type="list" 模式的特点也决定了它的局限性：它不会在返回的数据中包含文档的总数量（total 字段），也不支持像关键词搜索（q 参数）和自定义筛选这样的高级查询功能。这使得它不适用于需要分页展示或复杂搜索过滤的场景。
type=“page” 模式：构建完整分页与搜索功能的利器
与 type="list" 不同，type="page" 模式专为需要完整分页、搜索和高级筛选功能的场景而设计。如果您正在搭建一个博客列表页、新闻归档页或者产品展示中心，用户需要能够浏览所有内容、进行翻页操作，甚至通过关键词或特定属性来查找信息，那么 type="page" 模式就是您的首选。
当您将 type 设置为 "page" 时，接口不仅会返回当前页的文档列表数据，还会额外提供一个 total 字段，清晰地指示出所有符合查询条件的文档总数。这个 total 值是构建前端分页导航的关键，它让用户能直观地了解内容的整体规模，并轻松跳转到不同页面。
此外，type="page" 模式还解锁了多项高级功能。您可以配合 page 参数来指定获取第几页的内容，并与 limit 参数一起定义每页显示多少条文档。更强大的是，q 参数在此模式下可以用于进行关键词搜索，帮助用户快速定位标题中包含特定词汇的文档；同时，如果您在AnQiCMS后台配置了文档模型的自定义筛选字段，也可以通过URL查询参数的形式（例如 gender=男）来实现更细致的自定义筛选。
核心区别概览
总结来说，type="page" 和 type="list" 的主要区别体现在以下几个方面：
- 数据返回：
type="list"仅返回指定数量的文档，不包含总数；type="page"返回当前页文档列表，并提供total文档总数。 - 分页支持：
type="list"不支持page参数进行分页；type="page"支持page和limit参数实现完整的翻页功能。 - 高级查询：
type="list"不支持关键词搜索（q）和自定义筛选；type="page"完全支持这些功能，能够构建更具交互性的列表页面。 - 适用场景：
type="list"适用于快速获取小范围、固定数量的展示内容，如推荐位；type="page"适用于需要完整内容列表、分页浏览、搜索和筛选的归档页面。
在实际开发中，根据您的内容展示需求来选择合适的 type 模式，能够让您更高效地利用AnQiCMS的数据接口，避免不必要的数据传输，从而提升网站的加载速度和用户体验。
常见问题 (FAQ)
Q1：我可以使用 type="list" 模式来获取网站所有文章吗？
A1：不建议这样做。type="list" 模式的主要目的是获取少量数据，它不会返回总文章数，且一次性获取所有文章可能会因为数据量过大而导致请求响应慢，甚至超时。如果需要获取所有文章并进行分页展示，请务必使用 type="page" 模式。
Q2：在 type="list" 模式下，limit="5,10" 是什么意思？
A2：limit="5,10" 表示您希望从文档列表中跳过最前面的 5 条记录，然后从第 6 条记录开始，获取接下来的 10 条文档数据。这是一种“偏移量+数量”的获取方式，在某些特定的局部内容展示场景中非常实用。
Q3：为什么我在 type="list" 模式下使用 q 参数进行搜索，但没有生效？
A3：关键词搜索（q 参数）和自定义筛选功能是为 type="page" 模式设计的。type="list" 模式侧重于简单、固定数量的内容获取，因此不支持这些高级查询功能。如果您需要搜索或筛选文档，请务必将 type 参数设置为 page。