讀取頁面、部落格與資料集合

當您自己打造網站前端時，所有公開內容都可以直接從網站網址 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 ，在集合欄位變更時自動更新型別。

相關文件