Skip to main content

REST API：排序与分页

🌐 REST API: Sort & Pagination

Page summary:

使用 :asc 或 :desc 语法对 REST API 结果按一个或多个字段进行排序，并使用基于页码或基于偏移量的参数进行分页。

🌐 Sort REST API results on one or multiple fields with :asc or :desc syntax, and paginate using either page-based or offset-based parameters.

通过对 REST API 的查询返回的条目可以进行排序和分页。

🌐 Entries that are returned by queries to the REST API can be sorted and paginated.

Tip

Strapi 利用 `qs` 库 解析嵌套对象的能力来创建更复杂的查询。

🌐 Strapi takes advantage of the ability of the `qs` library to parse nested objects to create more complex queries.

直接使用 qs 来生成复杂查询，而不是手动创建它们。本说明文档中的示例展示了如何使用 qs。

🌐 Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.

如果你更喜欢使用我们的在线工具，而不是在你的机器上使用 qs 生成查询，你也可以使用 交互式查询构建器。

🌐 You can also use the interactive query builder if you prefer playing with our online tool instead of generating queries with qs on your machine.

排序​

🌐 Sorting

查询可以接受一个 sort 参数，该参数允许使用以下语法对一个或多个字段进行排序：

🌐 Queries can accept a sort parameter that allows sorting on one or multiple fields with the following syntaxes:

  • GET /api/:pluralApiId?sort=value 按 1 个字段排序
  • GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 按多个字段排序（例如按 2 个字段）

排序顺序可以定义为：

🌐 The sorting order can be defined with:

  • :asc 表示升序（默认顺序，可省略）
  • 或使用 :desc 表示降序。

示例：使用两个字段排序​

🌐 Example: Sort using 2 fields

你可以通过在 sort 数组中传入字段来按多个字段排序。

🌐 You can sort by multiple fields by passing fields in a sort array.

GET/api/restaurants?sort[0]=Description&sort[1]=Name

使用两个字段排序

按描述和名称字段排序结果。

terminal
curl 'http://localhost:1337/api/restaurants?sort[0]=Description&sort[1]=Name' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    },
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    }
    // …
  ],
  "meta": {
    // …
  }
}

示例：使用两个字段排序并设置顺序​

🌐 Example: Sort using 2 fields and set the order

使用 sort 参数并在已排序的字段上定义 :asc 或 :desc，你可以获得按特定顺序排序的结果。

🌐 Using the sort parameter and defining :asc or :desc on sorted fields, you can get results sorted in a particular order.

GET/api/restaurants?sort[0]=Description:asc&sort[1]=Name:desc

使用两个字段进行排序并设置顺序

按描述升序排列结果，按名称降序排列。

terminal
curl 'http://localhost:1337/api/restaurants?sort[0]=Description:asc&sort[1]=Name:desc' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    },
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ]
      // …
    }
    // …
  ],
  "meta": {
    // …
  }
}

分页​

🌐 Pagination

查询可以接受 pagination 参数。结果可以分页：

🌐 Queries can accept pagination parameters. Results can be paginated:

  • 可以通过 page（即，指定页码和每页条目数）
  • 或者通过 offset（即指定要跳过多少条条目以及要返回多少条）
Note

分页方法不能混合使用。始终要么使用 page 和 pageSize，或者使用 start 和 limit。

🌐 Pagination methods can not be mixed. Always use either page with pageSize or start with limit.

按页分页​

🌐 Pagination by page

要按页对结果进行分页，请使用以下参数：

🌐 To paginate results by page, use the following parameters:

参数类型描述默认值
pagination[page]整数页码1
pagination[pageSize]整数每页数量25
pagination[withCount]布尔值在响应中添加条目总数和页数True
GET/api/articles?pagination[page]=1&pagination[pageSize]=10

按页分页

仅在第1页显示10条记录。

terminal
curl 'http://localhost:1337/api/articles?pagination[page]=1&pagination[pageSize]=10' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 5,
      "total": 48
    }
  }
}

按偏移量分页​

🌐 Pagination by offset

要按偏移量对结果进行分页，请使用以下参数：

🌐 To paginate results by offset, use the following parameters:

参数类型描述默认值
pagination[start]整数起始值（即要返回的第一个条目）0
pagination[limit]整数要返回的条目数量25
pagination[withCount]布尔值切换是否在响应中显示条目总数true
Tip

pagination[limit] 的默认值和最大值可以在 /cms/configurations/api 文件中的 ./config/api.js 配置里通过 api.rest.defaultLimit 和 api.rest.maxLimit 键进行设置。

🌐 The default and maximum values for pagination[limit] can be configured in the ./config/api.js file with the api.rest.defaultLimit and api.rest.maxLimit keys.

GET/api/articles?pagination[start]=0&pagination[limit]=10

按偏移量分页

使用偏移量只返回前10个条目。

terminal
curl 'http://localhost:1337/api/articles?pagination[start]=0&pagination[limit]=10' \
  -H 'Authorization: Bearer <token>'
200 OK
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}
On this page