# 分頁

> 所有 Kanorio API 的列表端點皆採用 limit 與 cursor 參數，並回傳 data、hasMore 與 nextCursor。

> Markdown version of https://kanorio.com/zh-HK/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`。