读取页面、博客与数据集合

当您自行构建网站前端时，所有公开内容均可直接从网站域名 https://{您的网站}/api/v1/*（或永久系统域名 https://s-xxx.kanorio.com/api/v1/*）免密钥读取。

完整端点与参数规格（SSOT）：所有端点的查询参数、字段类型、筛选运算符与响应 JSON 示例，皆由 OpenAPI 规格实时生成于 Content Delivery API 参考页。本文聚焦于前端对接时的架构决策与常用模式。

这篇文章会协助您完成什么？

• 一次抓取网站外壳（页首导航、页尾、网站设置与重定向规则）
• 查询自定义数据集合与展开跨表关联（expand）、解析 assets 图片与模糊占位图（placeholder）
• 读取博客文章的多种正文格式（formats）、结构化分段（segments）与自动目录（toc）
• 在前端接入免密钥的站内搜索框（/api/v1/search）
• 用一行指令自动生成全站 TypeScript 类型（npx @kanorio/cli types）

1. 读取网站外壳、页面与重定向规则

如果您的外部前端希望沿用 Kanorio 后台设置的导航菜单、页尾链接或页面 SEO 设置，可以在共用 Layout 中读取：

• 网站基本信息（GET /api/v1/site）：获取网站名称、默认语言、时区、币种与当前公开内容版本 publicVersion。
• 页首与页尾（GET /api/v1/globals/headers/primary、GET /api/v1/globals/footer）：获取导航链接树、CTA 按钮、社交链接与 Logo（附带顶层 assets 媒体对照表）。
• 页面树与单页内容（GET /api/v1/pages、GET /api/v1/pages/{slug}）：获取页面层级、面包屑路径、SEO 字段（title、description、ogImage、canonicalUrl、noindex）与页面模块数据。首页可直接调用 /api/v1/pages/home。
• 重定向规则（GET /api/v1/redirects）：获取您在后台设置的重定向，以及页面改名时系统自动生成的 301 重定向列表，放入 Next.js Middleware 或边缘路由即可完整保留旧网址 SEO。

2. 查询数据集合与跨表关联（/api/v1/collections/{key}/items）

无论是在中建立的自定义集合（如 teachers、courses），还是系统自动同步的博客集合（blog、blog_categories、blog_tags、blog_authors），都使用同一套查询语法：

const res = await fetch(
  "https://s-k4m9x2p7q8w3.kanorio.com/api/v1/collections/courses/items?filter[level]=beginner&sort=-publishedAt&expand=teacher&limit=20"
);
const { items, nextCursor, assets } = await res.json();

对接时的四个实用技巧

1. 用 expand 一次展开引用数据： 若集合有 reference 或 multi_reference 字段（例如课程的 teacher、博客的 authors,categories,tags），加上 ?expand=teacher 后，每条项目会附上 item.expanded.teacher（包含对方的完整 fieldData），且被展开项目的图片也会一并收进顶层 assets 对照表，前端无需发起第二次请求。
2. 用 has_slug／eq_slug 直接按分类或标签代称筛选： 在制作分类页（如 /blog/category/recipes）时，不需要先查出分类 ID，直接写 ?filter[categories][has_slug]=recipes（单选引用则用 eq_slug），服务器会在同一条查询内完成比对。
3. 直接把 assets[id].placeholder 喂给图片组件： 顶层 assets 对照表中，每张位图都附带 url、width、height、alt 与 placeholder（16px WebP Base64 数据网址）。在 Next.js <Image placeholder="blur" blurDataURL={asset.placeholder} /> 中直接使用，即可零额外请求实现平滑的渐进式加载。
4. 用 fields 减少列表页传输量： 文章或商品列表页无需加载整篇长文时，可加上 ?fields=title,excerpt,cover_image,published_at，服务器只会返回指定字段。

3. 读取博客文章、目录与穿插行动号召

查询 /api/v1/collections/blog/items 或单篇 /api/v1/collections/blog/items/{slug} 时，可通过 ?formats= 控制正文返回格式：

• 默认（不带 formats）：fieldData.content 返回干净的 Markdown，同时项目顶层提供结构化的 segments 数组与 toc 标题目录数组（H2／H3 的 id、text、level）。
• 需要预先渲染好的 HTML 或纯文本摘要：带上 ?formats=html,plaintext（或 markdown,html,plaintext），fieldData 会额外附上 contentHtml 与 contentPlaintext。
• 渲染穿插在文章中的行动号召（CTA）：segments 数组将文章拆分为 { type: "markdown", markdown } 与 { type: "cta", presetId, title, description, buttonText, buttonUrl }，让您在自建前端用自己的 React／Astro 组件渲染文内促销卡。

4. 对接站内搜索（/api/v1/search）

想要在自建前端加上全站搜索框时，直接从浏览器或服务器调用：

const res = await fetch(
  `https://s-k4m9x2p7q8w3.kanorio.com/api/v1/search?q=${encodeURIComponent(keyword)}&kind=post,page,product&limit=10`
);
const { results } = await res.json();

• 搜索索引会在您发布页面、文章或商品时自动重建。
• kind 可筛选 page、post、product、category（逗号分隔）。
• 每条结果皆含 title、snippet（匹配片段）、url 与类型，适合直接做成即时下拉搜索菜单或 Command-K 搜索面板。

5. 自动生成 TypeScript 类型（kanorio types）

您无需手写任何集合字段的 TypeScript interface。在前端项目根目录执行：

npx @kanorio/cli types --site https://s-k4m9x2p7q8w3.kanorio.com --out src/kanorio.d.ts

CLI 会直接读取公开的 /api/v1/collections 自描述结构（含系统集合的虚拟字段 segments、toc、counts），一次产出所有集合的 FieldData、Expanded、Item 以及 /pages、/globals、/site 的完整类型定义。您也可以订阅 collections.schema.changed ，在集合字段变更时自动更新类型。

相关文档