排序和分页 Sort and Pagination

使用 Strapi 的 REST API 对数据进行排序或分页。可以对 REST API 查询返回的条目进行排序和分页。

Strapi 利用 qs 库 解析嵌套对象的能力来创建更复杂的查询。
直接使用 qs 生成复杂查询，而不是手动创建。本文档中的示例展示了如何使用 qs。
如果您更喜欢使用我们的在线工具，而不是在您的机器上使用 qs 生成查询，您也可以使用 交互式查询生成器。

排序

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

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

排序顺序可以这样定义：

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

示例：使用 2 个字段进行排序

您可以通过在“sort”数组中传递字段来按多个字段进行排序。

Example request: Sort using 2 fields
bash
GET /api/articles?sort[0]=title&sort[1]=slug
响应示例
json
{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article"
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article-1"
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}
js
const qs = require('qs')
const query = qs.stringify({
  sort: ['title', 'slug'],
}, {
  encodeValuesOnly: true, // prettify URL
})

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

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

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

示例请求：使用 2 个字段排序并设置顺序
bash
GET /api/articles?sort[0]=title:asc&sort[1]=slug:desc
响应示例
json
{
  "data": [
    {
      "id": 2,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article-1"
        // ...
      }
    },
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article"
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}
js
const qs = require('qs')
const query = qs.stringify({
  sort: ['title:asc', 'slug:desc'],
}, {
  encodeValuesOnly: true, // prettify URL
})

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

分页

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

  • 通过 page（即指定页码和每页的条目数）
  • 或通过 offset（即指定要跳过和返回的条目数）

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

按页分页

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

参数类型说明默认
pagination[page]整数页码1
pagination[pageSize]整数页面大小25
pagination[withCount]布尔值将条目总数和页数添加到响应中true

示例：

使用 pagination[page] 和 pagination[pageSize] 参数，您可以获得按页分页的结果：

Example request: Return only 10 entries on page 1
bash
GET /api/articles?pagination[page]=1&pagination[pageSize]=10
响应示例
json
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 5,
      "total": 48
    }
  }
}
js
const qs = require('qs')
const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10,
  },
}, {
  encodeValuesOnly: true, // prettify URL
})

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

按偏移量分页

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

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

可以使用 api.rest.defaultLimit 和 api.rest.maxLimit 键在 ./config/api.js](/dev-docs/configurations/api) 文件中配置 pagination[limit] 的默认值和最大值。

示例：

使用 pagination[start] 和 pagination[limit] 参数，您可以获得按偏移量分页的结果：

示例请求：使用偏移量仅返回前 10 个条目
bash
GET /api/articles?pagination[start]=0&pagination[limit]=10
响应示例
json
{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}
js
const qs = require('qs')
const query = qs.stringify({
  pagination: {
    start: 0,
    limit: 10,
  },
}, {
  encodeValuesOnly: true, // prettify URL
})

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