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 查询（使用 qs 库构建）：

¥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 查询（使用 qs 库构建）：

¥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 查询（使用 qs 库构建）：

¥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 查询（使用 qs 库构建）：

¥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
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}