REST API：排序与分页

🌐 REST API: Sort & Pagination

通过对 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

JavaScript 查询（使用 qs 库构建）：

上面的查询 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}`);

示例响应

{
  "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

JavaScript 查询（使用 qs 库构建）：

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

await request(`/api/restaurants?${query}`);

示例响应

{
  "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 |

示例请求：仅返回第1页的10个条目

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

JavaScript 查询（使用 qs 库构建）：

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

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

示例响应

{
  "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.

示例请求：使用偏移量仅返回前10条记录

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

JavaScript 查询（使用 qs 库构建）：

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

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

示例响应

{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}

排序​

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

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

分页​

按页分页​

按偏移量分页​

排序

示例：使用两个字段排序

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

分页

按页分页

按偏移量分页