# 筛选、字段与展开

> 在 Content Delivery API 读取中进行筛选、排序、投影字段、展开参考与解析媒体，每页仅需一个请求。

> Markdown version of https://kanorio.com/zh-CN/developers/basics/fields-and-expand. 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/fields-and-expand.md

Content Delivery API 的集合读取支持简易查询语言。此功能适用于您自定义的集合以及内置集合，例如 `blog`、`blog_categories`、`blog_tags` 与 `authors`。

```bash
curl "https://{site}/api/v1/collections/courses/items?filter[level]=beginner&sort=-publishedAt&fields=title,cover,teacher&expand=teacher&limit=12"
```

## 筛选 (Filter)

条件使用括号标记法：`filter[field][operator]=value`。`filter[field]=value` 是 `eq` 的简写。条件之间以 AND 结合。若要使用 OR，请将条件分组在 `filter[any][0]`、`filter[any][1]` 等之下。

| 运算符 | 适用于 | 示例 |
|---|---|---|
| `eq`, `ne` | 标量 | `filter[level][eq]=beginner` |
| `in`, `nin` | 标量，以逗号分隔的值 | `filter[level][in]=beginner,advanced` |
| `gt`, `gte`, `lt`, `lte` | 数字、日期 | `filter[price][lte]=50` |
| `contains`, `ncontains` | 文本 | `filter[title][contains]=bread` |
| `match` | 文本和富文本，多个单词 | `filter[content][match]=sourdough starter` |
| `exists` | 任何字段 | `filter[cover][exists]=true` |
| `has` | 多选、多引用 | `filter[tags][has]=tag_01` |
| `eq_slug` | 引用，通过引用项的别名 (slug) | `filter[teacher][eq_slug]=ada` |
| `has_slug` | 多引用，通过别名 (slug) | `filter[categories][has_slug]=recipes` |

`slug`、`publishedAt`、`createdAt` 与 `updatedAt` 在每个集合中皆可筛选。日期接受相对值，例如 `now-30d` 或 `now+1w`。参考文件列出了条件与值的确切限制。

## 排序 (Sort)

`sort=-publishedAt,title` 可依最多数个字段进行排序。开头的 `-` 代表降序。标量字段与上述项目属性皆可排序。富文本、JSON、媒体与多值字段则无法排序。

## 字段 (Fields)

`fields=title,excerpt,cover` 仅会返回 `fieldData` 中的指定键值。`id`、`slug`、`publishedAt` 与 `updatedAt` 永远会返回。请在列表页面使用此功能，以避免下载每篇文章的完整内容。

## 展开 (Expand)

`expand=teacher` 可取代一层参考查询。每个项目会取得包含参考项目的 `expanded.teacher`，其图像会加入顶层的 `assets` 映射表。在 `blog` 中，`expand=authors,categories,tags` 会展开文章的作者、分类与标签，而 `primary_author` 与 `primary_category` 会提供您各类别的第一个项目。

## 资源 (Assets)

图像、图库与文件字段会存储资源 ID。每个参考媒体的响应都会包含一个顶层的 `assets` 映射表来解析这些资源，因此您永远不需要发送第二次请求。

```json
{
  "assets": {
    "ast_01": {
      "assetId": "ast_01",
      "url": "https://imagedelivery.net/.../public",
      "width": 1600,
      "height": 1067,
      "alt": "Loaves cooling on a rack",
      "focus": { "x": 0.5, "y": 0.4 },
      "placeholder": "data:image/webp;base64,...",
      "edgeColor": "#f4efe6",
      "mimeType": "image/jpeg",
      "kind": "image"
    }
  }
}
```

- `placeholder` 是一个微小的模糊预览图，适用于 blur-up `<img>` 或 Next.js 的 `blurDataURL`。
- `focus` 是 0 到 1 坐标的焦点。当您进行裁剪时，请将其用于 `object-position`。若未设置，则为 `null`。
- `edgeColor` 是四个边缘共用的纯色，例如产品照片背后的白色。当您以 `object-fit: contain` 显示图像时，可将其作为背景。对于透明或多色图像，此值为 `null`；请改用 `placeholder` 作为模糊背景。
- 若要取得较小的图像，请将公开图像链接末尾的 `/public` 替换为变体，例如 `/w=800,fit=scale-down`。
- 当网站对图像进行水印处理时，`url` 即为已加上水印的版本。

## 格式 (Formats)

博客文章会在 `fieldData.content` 中返回 Markdown，并包含结构化的 `segments` 与标题的 `toc`。加入 `formats=html,plaintext` 即可额外取得 `contentHtml` 与 `plaintext`。`segments` 会将文章拆分为 Markdown 与嵌入区块（例如行动呼吁、FAQ 与图库），让您能使用自己的组件渲染每个区块。

## 受限内容 (Gated content)

当集合将字段限制为仅限会员或购买者存取时，匿名读取会省略这些字段并包含 `access`，例如 `{ "granted": false, "gated": ["content"], "requires": { "kind": "entitlement", "featureKey": "premium" } }`。请发送已登录顾客的 `knr_cat_` 令牌以取得完整项目。请根据每个项目自身的 `access` 进行渲染。

## 草稿 (Drafts)

加入 `preview=1` 并从您的服务器发送 `X-Kanorio-Preview: knr_pv_...` 即可读取未发布的草稿。请参阅 [验证](https://kanorio.com/zh-CN/developers/authentication)。