WordPress 站点可能包含大量内容——远超单次请求所能获取的数量。API 端点默认每次请求仅返回有限数量的项目，这与 WordPress 站点在归档视图中默认每页显示 10 篇帖子的方式相同。

分页参数

任何包含多个资源的 API 响应都支持几个通用的查询参数，用于处理响应数据中的分页：

  • ?page=：指定要返回的结果页码。
    • 例如，/wp/v2/posts?page=2 是帖子结果的第二页
    • 通过依次检索 /wp/v2/posts、/wp/v2/posts?page=2 等，您可以一次一页地访问 API 中所有可用的帖子。
  • ?per_page=：指定单次请求返回的记录数，以 1 到 100 之间的整数表示。
    • 例如，/wp/v2/posts?per_page=1 将仅返回集合中的第一篇帖子
  • ?offset=：指定开始检索帖子的任意偏移量
    • 例如，/wp/v2/posts?offset=6 将使用默认的每页帖子数量，但从集合中的第 6 篇帖子开始
    • ?per_page=5&page=4 等同于 ?per_page=5&offset=15

大型查询可能会影响站点性能，因此 per_page 上限为 100 条记录。如果您希望检索超过 100 条记录（例如构建客户端上所有可用类别的列表），您可以在应用程序内进行多次 API 请求并合并结果。

为了确定有多少页数据可用，API 会在每个分页响应中返回两个头部字段：

  • X-WP-Total：集合中的记录总数
  • X-WP-TotalPages：涵盖所有可用记录的总页数

通过检查这些头部字段，您可以确定 API 中还有多少更多数据可用。

排序结果

除了上述详细列出的分页查询参数外，还有几个其他参数控制返回结果的顺序：

  • ?order=：控制结果是按升序还是降序返回
    • 有效值为 ?order=asc（升序）和 ?order=desc（降序）。
    • 所有原生集合默认按降序返回。
  • ?orderby=：控制用于对集合进行排序的字段
    • orderby 的有效值会根据查询的资源而变化；对于 /wp/v2/posts 集合，有效值为"date"、"relevance"、"id"、"include"、"title"和"slug"
    • 有关其他集合支持的值，请参阅 REST API 参考
    • 所有包含日期资源集合的默认值为 orderby=date