云策 WordPress 开发者社区

REST API 文档

Pagination

查看官方原文 ↗
💡 云策文档标注

概述

本文档介绍了 WordPress REST API 中的分页机制，用于处理大量内容的分批请求。默认情况下，API 端点限制每页返回的项目数，类似于 WordPress 站点在归档视图中默认每页显示 10 篇文章。

关键要点

  • 分页参数：支持 ?page=、?per_page= 和 ?offset= 等查询参数来控制结果的分页和偏移。
  • 性能限制：per_page 参数上限为 100 条记录，超过需通过多次请求组合结果。
  • 分页信息：API 响应头包含 X-WP-Total 和 X-WP-TotalPages 字段，用于获取总记录数和总页数。
  • 排序控制：支持 ?order= 和 ?orderby= 参数来调整结果的排序顺序和字段。

代码示例

/wp/v2/posts?page=2
/wp/v2/posts?per_page=1
/wp/v2/posts?offset=6
/wp/v2/posts?per_page=5&page=4

注意事项

  • per_page 参数值必须在 1 到 100 之间，以避免影响站点性能。
  • orderby 参数的有效值取决于查询的资源类型，例如 /wp/v2/posts 支持 "date"、"relevance"、"id"、"include"、"title" 和 "slug"。
  • 默认排序：所有原生集合默认按降序返回，带日期的资源默认按日期排序。
📄 原文内容

WordPress sites can have a lot of content—far more than you’d want to pull down in a single request. The API endpoints default to providing a limited number of items per request, the same way that a WordPress site will default to 10 posts per page in archive views.

Pagination Parameters

Any API response which contains multiple resources supports several common query parameters to handle paging through the response data:

  • ?page=: specify the page of results to return.
    • For example, /wp/v2/posts?page=2 is the second page of posts results
    • By retrieving /wp/v2/posts, then /wp/v2/posts?page=2, and so on, you may access every available post through the API, one page at a time.
  • ?per_page=: specify the number of records to return in one request, specified as an integer from 1 to 100.
    • For example, /wp/v2/posts?per_page=1 will return only the first post in the collection
  • ?offset=: specify an arbitrary offset at which to start retrieving posts
    • For example, /wp/v2/posts?offset=6 will use the default number of posts per page, but start at the 6th post in the collection
    • ?per_page=5&page=4 is equivalent to ?per_page=5&offset=15
Large queries can hurt site performance, so per_page is capped at 100 records. If you wish to retrieve more than 100 records, for example to build a client-side list of all available categories, you may make multiple API requests and combine the results within your application.

To determine how many pages of data are available, the API returns two header fields with every paginated response:

  • X-WP-Total: the total number of records in the collection
  • X-WP-TotalPages: the total number of pages encompassing all available records

By inspecting these header fields you can determine how much more data is available within the API.

Ordering Results

In addition to the pagination query parameters detailed above, several other parameters control the order of the returned results:

  • ?order=: control whether results are returned in ascending or descending order
    • Valid values are ?order=asc (for ascending order) and ?order=desc (for descending order).
    • All native collections are returned in descending order by default.
  • ?orderby=: control the field by which the collection is sorted
    • The valid values for orderby will vary depending on the queried resource; for the /wp/v2/posts collection, the valid values are “date,” “relevance,” “id,” “include,” “title,” and “slug”
    • See the REST API reference for the values supported by other collections
    • All collections with dated resources default to orderby=date