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
和 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}`)