# 分页

> 所有 Kanorio API 的列表端点均采用 limit 与 cursor 参数，并返回 data、hasMore 与 nextCursor。

> Markdown version of https://kanorio.com/zh-CN/developers/basics/pagination. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/pagination.md

Management API、Content Delivery API 以及 Customer API 的所有列表端点均采用相同的分页方式。

## 请求

| 参数 | 类型 | 默认值 | 备注 |
|---|---|---|---|
| `limit` | 整数 | 20 | 范围从 1 到 100。部分端点会标注较低的上限。 |
| `cursor` | 字符串 | 无 | 来自前一页的 `nextCursor`。第一页请省略此参数。 |

## 响应

```json
{
  "data": [{ "id": "post_example01" }, { "id": "post_example02" }],
  "hasMore": true,
  "nextCursor": "eyJvIjoyMCwicyI6ImFiYzEyMyJ9"
}
```

| 字段 | 类型 | 备注 |
|---|---|---|
| `data` | 数组 | 此页面的项目，按照端点的顺序排列。 |
| `hasMore` | 布尔值 | 当还有下一页时为 `true`。 |
| `nextCursor` | 字符串或 null | 将其作为 `cursor` 传入以获取下一页。最后一页时为 `null`。 |

部分端点会在这些字段之外新增其他字段。例如，集合项目（collection items）会新增 `assets`，这是一个包含该页面所引用之所有图片与文件的映射表（map）。

## 规则

- **游标（Cursors）是不透明的。** 请勿解析、构建或长时间存储它们。其格式可能会在未经通知的情况下变更。
- **保留其他参数。** 游标仅适用于发出该游标时所使用的筛选条件、排序与限制。若在发送游标时使用不同的筛选条件，将会返回 `400 INVALID_CURSOR`。当筛选条件变更时，请重新开始，不要使用游标。
- **不支持页码或偏移量。** API 不接受 `page`、`pageSize` 或 `offset`。
- **默认不提供总数。** 计算每一笔符合的项目成本高昂，因此列表不会返回总数。Content Delivery API 有两个端点在您传入 `total=true` 时会返回 `total`：集合项目，以及搜索（总数与结果在同一次查询中算出）。
- **短列表仍使用封装格式。** 具有小型固定上限的列表（例如 Webhook 端点或重定向）会将所有内容返回在单一页面中，并将 `hasMore` 设为 `false`。相关参考页面会对此进行说明。

## 读取每一页

```bash
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

# then, while hasMore is true
curl "https://app.kanorio.com/api/v1/sites/ws_example123/posts?limit=50&cursor=eyJvIjo1MH0" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
```

SDK 的 `paginate` 会为您追踪 `nextCursor`，并适用于任何列表端点：

```ts
import { createManagementClient, paginate } from "@kanorio/sdk";

const client = createManagementClient({ token: process.env.KANORIO_TOKEN! });

for await (const post of paginate((cursor) =>
  client.get("/sites/{id}/posts", { params: { id: "ws_example123" }, query: { limit: 50, cursor } })
)) {
  console.log(post.slug);
}
```

当您需要将整个列表作为数组获取时，请使用 `listAll` 取代 `paginate`。