Skip to main content

REST API:排序和分页

¥REST API: Sort & Pagination

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

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

提示

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=value to sort on 1 field

  • GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 对多个字段进行排序（例如在 2 个字段上）

    ¥GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 to sort on multiple fields (e.g. on 2 fields)

排序顺序可以定义为：

¥The sorting order can be defined with:

  • :asc 为升序（默认顺序，可省略）

    ¥:asc for ascending order (default order, can be omitted)

  • 或 :desc 表示降序排列。

    ¥or :desc for descending order.

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

¥Example: Sort using 2 fields

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

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


Example request: Sort using 2 fields

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

JavaScript query (built with the qs library):

上面的查询 URL 是使用 `qs` 库  构建的。qs 可以在你的计算机上本地运行，如以下代码示例所示，或者你也可以使用我们的 交互式查询构建器 在线工具。

¥The query URL above was built using the `qs` library . qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description', 'Name'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);
Example response
{
  "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": {
    // …
  }
}

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

¥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.


Example request: Sort using 2 fields and set the order

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

JavaScript query (built with the qs library):

上面的查询 URL 是使用 `qs` 库  构建的。qs 可以在你的计算机上本地运行，如以下代码示例所示，或者你也可以使用我们的 交互式查询构建器 在线工具。

¥The query URL above was built using the `qs` library . qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description:asc', 'Name:desc'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);
Example response
{
  "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（即指定页码和每页的条目数）

    ¥either by page (i.e., specifying a page number and the number of entries per page)

  • 或按 offset（即指定要跳过和返回的条目数）

    ¥or by offset (i.e., specifying how many entries to skip and to return)

注意

分页方法不能混合。始终使用 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]布尔值将条目总数和页数添加到响应中真的
Example request: Return only 10 entries on page 1

GET /api/articles?pagination[page]=1&pagination[pageSize]=10

JavaScript query (built with the qs library):

上面的查询 URL 是使用 `qs` 库  构建的。qs 可以在你的计算机上本地运行，如以下代码示例所示，或者你也可以使用我们的 交互式查询构建器 在线工具。

¥The query URL above was built using the `qs` library . qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10,
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);
Example response
{
  "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
提示

pagination[limit] 的默认值和最大值可以是带有 api.rest.defaultLimit 和 api.rest.maxLimit 键的 在 ./config/api.js 中配置 文件。

¥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.

Example request: Return only the first 10 entries using offset

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

JavaScript query (built with the qs library):

上面的查询 URL 是使用 `qs` 库  构建的。qs 可以在你的计算机上本地运行，如以下代码示例所示，或者你也可以使用我们的 交互式查询构建器 在线工具。

¥The query URL above was built using the `qs` library . qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    start: 0,
    limit: 10,
  },
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/articles?${query}`);
Example response

!!!IG3!!!