容查詢與渲染指南：用 getEmDashCollection / getEmDashEntry 構(gòu)建 Astro 驅(qū)動的內(nèi)容站點)
CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMSWordPress 的現(xiàn)代后繼者其核心能力之一是把 CMS 內(nèi)容無縫暴露給前端頁面在.astro頁面中通過emdash包提供的查詢函數(shù)按集合collection取數(shù)、渲染 Portable Text 富文本、輸出 CMS 圖片并開啟可視化編輯。本篇指南以 querying-and-rendering.md 為骨架逐項講解內(nèi)容查詢 API、緩存集成、富文本與圖片渲染、分頁、SEO 元數(shù)據(jù)與常見頁面模式并結(jié)合 query.ts 等源碼說明底層實現(xiàn)幫助你在自己的 EmDash 站點上寫出類型安全、可緩存、可點選編輯的頁面。內(nèi)容查詢 API 總覽EmDash 的查詢函數(shù)統(tǒng)一從emdash包導(dǎo)入它們在內(nèi)部包裝 Astro 的getLiveCollection/getLiveEntry并附加類型過濾與內(nèi)容水合bylines、taxonomy terms源碼入口見 index.ts 的 re-export 與 query.ts。核心函數(shù)有兩個getEmDashCollection(type, filter?)—— 獲取一個集合的多條條目返回{ entries, error, cacheHint, nextCursor }getEmDashEntry(type, id, options?)—— 按 slug或數(shù)據(jù)庫 ID獲取單條條目返回{ entry, error, isPreview, cacheHint }。兩個函數(shù)都遵循“錯誤不拋出、隨結(jié)果返回”的 Astro 風(fēng)格集合查詢在出錯時返回空entries數(shù)組并附帶error字段單條查詢在未找到時entry為null這不屬于錯誤只有真正的數(shù)據(jù)庫異常才會設(shè)置error。因此頁面里可以直接用if (!post) return Astro.redirect(/404)處理不存在的情況。集合查詢getEmDashCollection最基本的用法是不帶任何過濾條件取回整個集合import { getEmDashCollection } from emdash; // Basic const { entries: posts } await getEmDashCollection(posts);帶選項的用法如下// With options const { entries: posts, cacheHint } await getEmDashCollection(posts, { status: published, limit: 10, orderBy: { published_at: desc }, where: { category: news }, });選項說明與源碼中 CollectionFilterBase 的定義一致選項類型說明statusdraft \| published \| archived按內(nèi)容狀態(tài)過濾limitnumber返回的最大條目數(shù)cursorstring不透明游標用于 keyset 分頁把上一次結(jié)果的nextCursor傳進來即可翻頁offsetnumber偏移分頁的跳過條數(shù)與cursor互斥同時傳入在編譯期報錯orderBy{ field: asc \| desc }排序字段與方向默認{ created_at: desc }也支持多字段如{ published_at: desc, title: asc }whereRecordstring, WhereValue按字段值、taxonomy 詞條或 byline 過濾數(shù)組表示 OR 語義如{ category: [news, featured] }還支持日期范圍{ published_at: { gte: 2024-01-01, lt: 2025-01-01 } }localestring配置了 i18n 時按語言過濾如en/frwhere的細節(jié)值得展開taxonomy 名稱會被自動識別并走 JOIN 過濾如{ category: news }過濾歸類到該詞條的條目保留鍵byline會通過_emdash_content_bylines中間表按署名過濾含合著條目{ byline: [01HXYZ..., 01HABC...] }表示任一署名匹配其余鍵則作為內(nèi)容表的列過濾。見 query.ts 的注釋與示例。單條查詢getEmDashEntryimport { getEmDashEntry } from emdash; const { entry: post, cacheHint } await getEmDashEntry(posts, slug); if (!post) { return Astro.redirect(/404); }getEmDashEntry接受可選的{ locale }選項。在配置了 i18n 時它會沿著“請求語言 → fallback 語言 → 默認語言”的 fallback 鏈解析命中的條目會在結(jié)果中帶出fallbackLocale字段預(yù)覽_previewtoken與編輯模式由中間件通過 AsyncLocalStorage 注入請求上下文查詢函數(shù)自動讀取無需額外傳參見 query.ts 的 locale 鏈與 draft 分支邏輯。Entry 結(jié)構(gòu)與“兩個 id”的陷阱查詢返回的每條 entry 都是統(tǒng)一的ContentEntryT形狀interface ContentEntryT { id: string; // The slug (used in URLs) data: T; // All fields, including system fields edit: EditProxy; // Visual editing attributes (spread onto elements) }data中既包含系統(tǒng)字段也包含你在 CMS 里定義的自定義字段。以一篇 post 為例interface PostData { id: string; // Database ULID (use for taxonomy lookups, etc.) slug: string; status: string; title: string; featured_image?: { id: string; src?: string; alt?: string; width?: number; height?: number; }; content?: PortableTextBlock[]; createdAt: Date; updatedAt: Date; publishedAt: Date | null; // Bylines (eagerly loaded) byline: BylineSummary | null; // Primary author bylines: ContentBylineCredit[]; // All credits (with roleLabel, source) // ... your custom fields }最重要的一個約定entry.id是 slug用于拼 URLentry.data.id才是數(shù)據(jù)庫 ULID用于調(diào)用getEntryTerms等 API。千萬不要混用二者URL 用entry.id如/posts/${post.id}而需要按數(shù)據(jù)庫主鍵做查詢例如取 taxonomy terms時必須傳entry.data.id。從源碼看entryDatabaseId正是讀取data.idquery.ts。另外注意bylines/byline是**急切水合eagerly hydrated**的字段——查詢返回時已附帶署名數(shù)據(jù)不需要額外請求taxonomy terms 則被水合到entry.data.terms按 taxonomy 名稱分組的TaxonomyTerm[]對象這意味著列表頁循環(huán)條目時無需再逐條調(diào)用getEntryTerms造成 N1 查詢見 query.ts 的批量 JOIN 實現(xiàn)。緩存永遠調(diào)用 Astro.cache.set(cacheHint)查詢結(jié)果都帶有cacheHint用于 Astro 的 Route Caching內(nèi)容變更時自動失效緩存--- const { entries: posts, cacheHint } await getEmDashCollection(posts); Astro.cache.set(cacheHint); ---請務(wù)必調(diào)用Astro.cache.set(cacheHint)——它讓頁面在 CMS 內(nèi)容更新時自動失效并重建是生產(chǎn)站點緩存一致性的前提。從實現(xiàn)看集合與單條查詢都經(jīng)過請求級緩存同一渲染周期內(nèi)相同(type, filter)的重復(fù)查詢只執(zhí)行一次與分布式對象緩存L2按collection filter 有效 locale緩存 JSON 快照見 query.tscacheHint攜帶的tags/lastModified就是給路由緩存做失效判斷的依據(jù)。此外對于limit小于 10 的小型“最近 N 篇”組件查詢層會把 limit 歸并到共享桶bucket以合并重復(fù)取數(shù)所以多個側(cè)邊欄小組件同時渲染也不會各自查庫query.ts。渲染 Portable TextCMS 里的富文本字段如content是 Portable Text 塊數(shù)組用emdash/ui的PortableText組件渲染--- import { PortableText } from emdash/ui; --- PortableText value{post.data.content} /它內(nèi)置支持標準塊段落、標題、列表、引用、代碼塊、圖片與行內(nèi)標記加粗、斜體、代碼、刪除線、鏈接。組件源碼見 PortableText.astro并從 components/index.ts 統(tǒng)一導(dǎo)出。自定義塊類型營銷頁通常需要自定義塊如 hero、features 等 CMS 區(qū)塊。通過componentsprop 傳入類型到組件的映射--- import { PortableText } from emdash/ui; import Hero from ./blocks/Hero.astro; import Features from ./blocks/Features.astro; const customTypes { marketing.hero: Hero, marketing.features: Features, }; --- PortableText value{page.data.content} components{{ type: customTypes }} /每個自定義組件會收到該 block 的數(shù)據(jù)作為 props你可以在組件內(nèi)部讀取字段并自行排版。Image 組件CMS 圖片字段是對象不是字符串CMS 中的圖片字段一律是對象含id、src、alt、width、height等必須使用 EmDash 的Image組件渲染。正確與錯誤的寫法對比--- import { Image } from emdash/ui; --- {/* Correct -- passes the image object */} Image image{post.data.featured_image} / {/* Also works with explicit props */} {post.data.featured_image?.src ( img src{post.data.featured_image.src} alt{post.data.featured_image.alt || } / )}{/* WRONG -- image is an object, not a string */} img src{post.data.featured_image} /把對象直接塞給原生img src是新手最常見的錯誤渲染結(jié)果是[object Object]。Image組件源碼見 Image.astro 與 EmDashImage.astro處理對象并輸出正確的img屬性如果確實要用原生標簽務(wù)必像上面的“顯式 props”寫法那樣取.src與.alt?？梢暬庉嬚归_ entry.edit 屬性每條 entry 都攜帶edit代理對象把它展開到展示對應(yīng)字段的元素上即可啟用“點擊即編輯”h1 {...post.edit.title}{post.data.title}/h1 p {...post.edit.excerpt}{post.data.excerpt}/p div {...post.edit.featured_image} Image image{post.data.featured_image} / /div當管理員登錄并瀏覽站點時這些屬性會附加編輯標注實現(xiàn)行內(nèi)點選編輯普通訪客拿到的是 no-op 版本展開后不產(chǎn)生任何副作用。實現(xiàn)上createEditable/createNoopvisual-editing/editable.ts 的引入處會根據(jù)請求上下文是否編輯模式?jīng)Q定附加真實代理還是空操作Portable Text 數(shù)組還會被貼上非枚舉的編輯元數(shù)據(jù)tagEditableFields見 query.ts讓富文本字段同樣可被編輯定位。常見頁面模式列表頁如/posts/index.astro--- import { getEmDashCollection, getEntryTerms } from emdash; import { Image } from emdash/ui; import Base from ../../layouts/Base.astro; const { entries: posts, cacheHint } await getEmDashCollection(posts, { orderBy: { published_at: desc }, }); Astro.cache.set(cacheHint); const sortedPosts posts.toSorted((a, b) { const dateA a.data.publishedAt?.getTime() ?? 0; const dateB b.data.publishedAt?.getTime() ?? 0; return dateB - dateA; }); --- Base titlePosts {sortedPosts.map(post ( article {post.data.featured_image Image image{post.data.featured_image} /} a href{/posts/${post.id}}{post.data.title}/a {post.data.excerpt p{post.data.excerpt}/p} /article ))} /Base注意publishedAt是Date對象所以手動排序要用getTime()比較鏈接一律使用post.idslug。詳情頁如/posts/[slug].astro--- import { getEmDashEntry, getEntryTerms, getSeoMeta } from emdash; import { Image, PortableText } from emdash/ui; import Base from ../../layouts/Base.astro; const { slug } Astro.params; if (!slug) return Astro.redirect(/404); const { entry: post, cacheHint } await getEmDashEntry(posts, slug); if (!post) return Astro.redirect(/404); Astro.cache.set(cacheHint); const seo getSeoMeta(post, { siteTitle: My Blog, siteUrl: Astro.url.origin, path: /posts/${slug}, }); const tags await getEntryTerms(posts, post.data.id, tag); --- Base title{seo.title} description{seo.description} article {post.data.featured_image ( div {...post.edit.featured_image} Image image{post.data.featured_image} / /div )} h1 {...post.edit.title}{post.data.title}/h1 PortableText value{post.data.content} / {tags.length 0 ( div {tags.map(t a href{/tag/${t.slug}}{t.label}/a)} /div )} /article /Base這里示范了三個要點getSeoMeta導(dǎo)出自 seo/index.ts根據(jù) entry 生成 SEO 標題與描述getEntryTerms(posts, post.data.id, tag)必須傳數(shù)據(jù)庫 ULIDpost.data.id而非 slug可視化編輯屬性與Image/PortableText組合使用。分類歸檔頁如/category/[slug].astro--- import { getTerm, getEmDashCollection } from emdash; import Base from ../../layouts/Base.astro; const { slug } Astro.params; const term slug ? await getTerm(category, slug) : null; if (!term) return Astro.redirect(/404); const { entries: posts } await getEmDashCollection(posts, { where: { category: term.slug }, orderBy: { published_at: desc }, }); --- Base title{${term.label} posts} h1{term.label}/h1 {posts.map(post ( a href{/posts/${post.id}}{post.data.title}/a ))} /BasegetTerm按(taxonomy, slug)取單個詞條含 label、slug、children 等并支持 locale fallback 鏈與可選的可見條目計數(shù)includeCounts: false可跳過計數(shù)查詢實現(xiàn)見 taxonomies/index.ts。歸檔頁隨后用where: { category: term.slug }過濾出該分類下的條目。RSS 源如/rss.xml.tsimport type { APIRoute } from astro; import { getEmDashCollection } from emdash; const siteTitle My Site; export const GET: APIRoute async ({ url }) { const siteUrl url.origin; const { entries: posts } await getEmDashCollection(posts, { orderBy: { published_at: desc }, limit: 20, }); const items posts .filter((p) p.data.publishedAt) .map((post) { const postUrl ${siteUrl}/posts/${post.id}; return item title${escapeXml(post.data.title)}/title link${postUrl}/link guid isPermaLinktrue${postUrl}/guid pubDate${post.data.publishedAt!.toUTCString()}/pubDate description${escapeXml(post.data.excerpt || )}/description /item; }) .join(\n); return new Response( ?xml version1.0 encodingUTF-8? rss version2.0 xmlns:atomhttp://www.w3.org/2005/Atom channel title${escapeXml(siteTitle)}/title link${siteUrl}/link atom:link href${siteUrl}/rss.xml relself typeapplication/rssxml/ languageen-us/language lastBuildDate${new Date().toUTCString()}/lastBuildDate ${items} /channel /rss, { headers: { Content-Type: application/rssxml; charsetutf-8, Cache-Control: public, max-age3600, }, }, ); }; function escapeXml(s: string): string { return s .replace(//g, amp;) .replace(//g, lt;) .replace(//g, gt;) .replace(//g, quot;) .replace(//g, apos;); }要點過濾掉未發(fā)布的條目p.data.publishedAt為 null 的過濾掉、用entry.id拼 URL、用toUTCString()輸出 RFC 822 時間并對所有動態(tài)文本做 XML 轉(zhuǎn)義。404 頁面/404.astro--- import Base from ../layouts/Base.astro; --- Base titleNot Found h1Page not found/h1 pThe page youre looking for doesnt exist./p a href/Go home/a /Base空狀態(tài)當集合還沒有內(nèi)容時展示一個友好的空狀態(tài)引導(dǎo)去后臺創(chuàng)建第一篇內(nèi)容{posts.length 0 ? ( section h2No posts yet/h2 pCreate your first post in the admin panel./p a href/_emdash/admin/content/posts/newCreate a post/a /section ) : ( /* ... render posts ... */ )}分頁cursor 與 offset 兩種方式getEmDashCollection內(nèi)置兩種互斥的分頁方式keyset 游標分頁cursor與偏移分頁offset。源碼中的類型定義保證了二者不能同時傳入同時提供在編譯期報錯見 query.ts。游標分頁推薦用于“下一頁”翻頁把上一次結(jié)果的nextCursor傳入下一次請求的cursor即可nextCursor為undefined表示沒有更多結(jié)果--- const cursor Astro.url.searchParams.get(cursor) ?? undefined; const { entries, nextCursor, cacheHint } await getEmDashCollection(posts, { limit: 10, cursor, orderBy: { published_at: desc }, }); Astro.cache.set(cacheHint); --- {entries.map(post ( a href{/posts/${post.id}}{post.data.title}/a ))} {nextCursor a href{?cursor${nextCursor}}Next page/a}游標是不透明字符串由查詢層按“排序值 數(shù)據(jù)庫 ID”編碼encodeEntryCursor見 query.ts編碼時對日期列優(yōu)先使用原始存儲字符串以避免時區(qū)/精度損耗因此翻頁穩(wěn)定、不受新插入數(shù)據(jù)影響。偏移分頁用于/page/2這類編號歸檔結(jié)果中的hasMore表示是否還有后續(xù)條目適合渲染“下一頁”鏈接而無需計算總數(shù)const perPage 20; const { entries, hasMore } await getEmDashCollection(posts, { limit: perPage, offset: (page - 1) * perPage, orderBy: { published_at: desc }, });兩種方式下只要傳了limit結(jié)果都會附帶hasMore字段默認limit 1探測法判斷見 query.ts。日期格式化查詢返回的日期字段createdAt、updatedAt、publishedAt都是Date對象直接用toLocaleDateString或Intl.DateTimeFormat格式化const formatted post.data.publishedAt?.toLocaleDateString(en-US, { year: numeric, month: long, day: numeric, });注意publishedAt可能為null未發(fā)布取值時要先判空如可選鏈?.。實戰(zhàn)要點小結(jié)所有查詢函數(shù)從emdash導(dǎo)入類型由生成到站點里的emdash-env.d.ts提供EmDashCollections接口擴展后集合名與字段自動獲得類型推斷見 query.ts拼錯集合名或字段名會得到編譯期錯誤每次查詢后都調(diào)用Astro.cache.set(cacheHint)保證內(nèi)容變更自動失效緩存URL 用entry.idslug數(shù)據(jù)庫 API如getEntryTerms用entry.data.idULIDCMS 圖片必須用Image組件傳對象不要直接src{對象}富文本用PortableText自定義 CMS 區(qū)塊通過components{{ type: {...} }}注入管理端登錄后把post.edit.*展開到元素上即獲得行內(nèi)點選編輯能力列表、詳情、歸檔、RSS、404、空狀態(tài)、分頁、日期格式化可直接復(fù)制上面的代碼模式改造到自己的站點。贊分享CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載相關(guān)推薦EmDash 內(nèi)容查詢與渲染實戰(zhàn)從 getEmDashCollection 到 Portable Text 的完整指南EmDash 內(nèi)容查詢與渲染實戰(zhàn)從 getEmDashCollection 到 Portable Text 的完整指南 這篇技術(shù)指南圍繞 EmDash 前端模CMS后端前端插件系統(tǒng)EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、Portable Text 與可視化編輯EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、Portable Text 與可視化編輯 EmDash 是一個基于 Astro 的CMS后端前端插件系統(tǒng)EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、PortableText 與常見頁面模式EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、PortableText 與常見頁面模式 導(dǎo)讀 本文基于 EmDash 官方站點構(gòu)CMS后端前端插件系統(tǒng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 EmDash 內(nèi)容查詢與渲染指南：用 getEmDashCollection / getEmDashEntry 構(gòu)建 Astro 驅(qū)動的內(nèi)容站點
CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMSWordPress 的現(xiàn)代后繼者其核心能力之一是把 CMS 內(nèi)容無縫暴露給前端頁面在.astro頁面中通過emdash包提供的查詢函數(shù)按集合collection取數(shù)、渲染 Portable Text 富文本、輸出 CMS 圖片并開啟可視化編輯。本篇指南以 querying-and-rendering.md 為骨架逐項講解內(nèi)容查詢 API、緩存集成、富文本與圖片渲染、分頁、SEO 元數(shù)據(jù)與常見頁面模式并結(jié)合 query.ts 等源碼說明底層實現(xiàn)幫助你在自己的 EmDash 站點上寫出類型安全、可緩存、可點選編輯的頁面。內(nèi)容查詢 API 總覽EmDash 的查詢函數(shù)統(tǒng)一從emdash包導(dǎo)入它們在內(nèi)部包裝 Astro 的getLiveCollection/getLiveEntry并附加類型過濾與內(nèi)容水合bylines、taxonomy terms源碼入口見 index.ts 的 re-export 與 query.ts。核心函數(shù)有兩個getEmDashCollection(type, filter?)—— 獲取一個集合的多條條目返回{ entries, error, cacheHint, nextCursor }getEmDashEntry(type, id, options?)—— 按 slug或數(shù)據(jù)庫 ID獲取單條條目返回{ entry, error, isPreview, cacheHint }。兩個函數(shù)都遵循“錯誤不拋出、隨結(jié)果返回”的 Astro 風(fēng)格集合查詢在出錯時返回空entries數(shù)組并附帶error字段單條查詢在未找到時entry為null這不屬于錯誤只有真正的數(shù)據(jù)庫異常才會設(shè)置error。因此頁面里可以直接用if (!post) return Astro.redirect(/404)處理不存在的情況。集合查詢getEmDashCollection最基本的用法是不帶任何過濾條件取回整個集合import { getEmDashCollection } from emdash; // Basic const { entries: posts } await getEmDashCollection(posts);帶選項的用法如下// With options const { entries: posts, cacheHint } await getEmDashCollection(posts, { status: published, limit: 10, orderBy: { published_at: desc }, where: { category: news }, });選項說明與源碼中 CollectionFilterBase 的定義一致選項類型說明statusdraft \| published \| archived按內(nèi)容狀態(tài)過濾limitnumber返回的最大條目數(shù)cursorstring不透明游標用于 keyset 分頁把上一次結(jié)果的nextCursor傳進來即可翻頁offsetnumber偏移分頁的跳過條數(shù)與cursor互斥同時傳入在編譯期報錯orderBy{ field: asc \| desc }排序字段與方向默認{ created_at: desc }也支持多字段如{ published_at: desc, title: asc }whereRecordstring, WhereValue按字段值、taxonomy 詞條或 byline 過濾數(shù)組表示 OR 語義如{ category: [news, featured] }還支持日期范圍{ published_at: { gte: 2024-01-01, lt: 2025-01-01 } }localestring配置了 i18n 時按語言過濾如en/frwhere的細節(jié)值得展開taxonomy 名稱會被自動識別并走 JOIN 過濾如{ category: news }過濾歸類到該詞條的條目保留鍵byline會通過_emdash_content_bylines中間表按署名過濾含合著條目{ byline: [01HXYZ..., 01HABC...] }表示任一署名匹配其余鍵則作為內(nèi)容表的列過濾。見 query.ts 的注釋與示例。單條查詢getEmDashEntryimport { getEmDashEntry } from emdash; const { entry: post, cacheHint } await getEmDashEntry(posts, slug); if (!post) { return Astro.redirect(/404); }getEmDashEntry接受可選的{ locale }選項。在配置了 i18n 時它會沿著“請求語言 → fallback 語言 → 默認語言”的 fallback 鏈解析命中的條目會在結(jié)果中帶出fallbackLocale字段預(yù)覽_previewtoken與編輯模式由中間件通過 AsyncLocalStorage 注入請求上下文查詢函數(shù)自動讀取無需額外傳參見 query.ts 的 locale 鏈與 draft 分支邏輯。Entry 結(jié)構(gòu)與“兩個 id”的陷阱查詢返回的每條 entry 都是統(tǒng)一的ContentEntryT形狀interface ContentEntryT { id: string; // The slug (used in URLs) data: T; // All fields, including system fields edit: EditProxy; // Visual editing attributes (spread onto elements) }data中既包含系統(tǒng)字段也包含你在 CMS 里定義的自定義字段。以一篇 post 為例interface PostData { id: string; // Database ULID (use for taxonomy lookups, etc.) slug: string; status: string; title: string; featured_image?: { id: string; src?: string; alt?: string; width?: number; height?: number; }; content?: PortableTextBlock[]; createdAt: Date; updatedAt: Date; publishedAt: Date | null; // Bylines (eagerly loaded) byline: BylineSummary | null; // Primary author bylines: ContentBylineCredit[]; // All credits (with roleLabel, source) // ... your custom fields }最重要的一個約定entry.id是 slug用于拼 URLentry.data.id才是數(shù)據(jù)庫 ULID用于調(diào)用getEntryTerms等 API。千萬不要混用二者URL 用entry.id如/posts/${post.id}而需要按數(shù)據(jù)庫主鍵做查詢例如取 taxonomy terms時必須傳entry.data.id。從源碼看entryDatabaseId正是讀取data.idquery.ts。另外注意bylines/byline是**急切水合eagerly hydrated**的字段——查詢返回時已附帶署名數(shù)據(jù)不需要額外請求taxonomy terms 則被水合到entry.data.terms按 taxonomy 名稱分組的TaxonomyTerm[]對象這意味著列表頁循環(huán)條目時無需再逐條調(diào)用getEntryTerms造成 N1 查詢見 query.ts 的批量 JOIN 實現(xiàn)。緩存永遠調(diào)用 Astro.cache.set(cacheHint)查詢結(jié)果都帶有cacheHint用于 Astro 的 Route Caching內(nèi)容變更時自動失效緩存--- const { entries: posts, cacheHint } await getEmDashCollection(posts); Astro.cache.set(cacheHint); ---請務(wù)必調(diào)用Astro.cache.set(cacheHint)——它讓頁面在 CMS 內(nèi)容更新時自動失效并重建是生產(chǎn)站點緩存一致性的前提。從實現(xiàn)看集合與單條查詢都經(jīng)過請求級緩存同一渲染周期內(nèi)相同(type, filter)的重復(fù)查詢只執(zhí)行一次與分布式對象緩存L2按collection filter 有效 locale緩存 JSON 快照見 query.tscacheHint攜帶的tags/lastModified就是給路由緩存做失效判斷的依據(jù)。此外對于limit小于 10 的小型“最近 N 篇”組件查詢層會把 limit 歸并到共享桶bucket以合并重復(fù)取數(shù)所以多個側(cè)邊欄小組件同時渲染也不會各自查庫query.ts。渲染 Portable TextCMS 里的富文本字段如content是 Portable Text 塊數(shù)組用emdash/ui的PortableText組件渲染--- import { PortableText } from emdash/ui; --- PortableText value{post.data.content} /它內(nèi)置支持標準塊段落、標題、列表、引用、代碼塊、圖片與行內(nèi)標記加粗、斜體、代碼、刪除線、鏈接。組件源碼見 PortableText.astro并從 components/index.ts 統(tǒng)一導(dǎo)出。自定義塊類型營銷頁通常需要自定義塊如 hero、features 等 CMS 區(qū)塊。通過componentsprop 傳入類型到組件的映射--- import { PortableText } from emdash/ui; import Hero from ./blocks/Hero.astro; import Features from ./blocks/Features.astro; const customTypes { marketing.hero: Hero, marketing.features: Features, }; --- PortableText value{page.data.content} components{{ type: customTypes }} /每個自定義組件會收到該 block 的數(shù)據(jù)作為 props你可以在組件內(nèi)部讀取字段并自行排版。Image 組件CMS 圖片字段是對象不是字符串CMS 中的圖片字段一律是對象含id、src、alt、width、height等必須使用 EmDash 的Image組件渲染。正確與錯誤的寫法對比--- import { Image } from emdash/ui; --- {/* Correct -- passes the image object */} Image image{post.data.featured_image} / {/* Also works with explicit props */} {post.data.featured_image?.src ( img src{post.data.featured_image.src} alt{post.data.featured_image.alt || } / )}{/* WRONG -- image is an object, not a string */} img src{post.data.featured_image} /把對象直接塞給原生img src是新手最常見的錯誤渲染結(jié)果是[object Object]。Image組件源碼見 Image.astro 與 EmDashImage.astro處理對象并輸出正確的img屬性如果確實要用原生標簽務(wù)必像上面的“顯式 props”寫法那樣取.src與.alt?？梢暬庉嬚归_ entry.edit 屬性每條 entry 都攜帶edit代理對象把它展開到展示對應(yīng)字段的元素上即可啟用“點擊即編輯”h1 {...post.edit.title}{post.data.title}/h1 p {...post.edit.excerpt}{post.data.excerpt}/p div {...post.edit.featured_image} Image image{post.data.featured_image} / /div當管理員登錄并瀏覽站點時這些屬性會附加編輯標注實現(xiàn)行內(nèi)點選編輯普通訪客拿到的是 no-op 版本展開后不產(chǎn)生任何副作用。實現(xiàn)上createEditable/createNoopvisual-editing/editable.ts 的引入處會根據(jù)請求上下文是否編輯模式?jīng)Q定附加真實代理還是空操作Portable Text 數(shù)組還會被貼上非枚舉的編輯元數(shù)據(jù)tagEditableFields見 query.ts讓富文本字段同樣可被編輯定位。常見頁面模式列表頁如/posts/index.astro--- import { getEmDashCollection, getEntryTerms } from emdash; import { Image } from emdash/ui; import Base from ../../layouts/Base.astro; const { entries: posts, cacheHint } await getEmDashCollection(posts, { orderBy: { published_at: desc }, }); Astro.cache.set(cacheHint); const sortedPosts posts.toSorted((a, b) { const dateA a.data.publishedAt?.getTime() ?? 0; const dateB b.data.publishedAt?.getTime() ?? 0; return dateB - dateA; }); --- Base titlePosts {sortedPosts.map(post ( article {post.data.featured_image Image image{post.data.featured_image} /} a href{/posts/${post.id}}{post.data.title}/a {post.data.excerpt p{post.data.excerpt}/p} /article ))} /Base注意publishedAt是Date對象所以手動排序要用getTime()比較鏈接一律使用post.idslug。詳情頁如/posts/[slug].astro--- import { getEmDashEntry, getEntryTerms, getSeoMeta } from emdash; import { Image, PortableText } from emdash/ui; import Base from ../../layouts/Base.astro; const { slug } Astro.params; if (!slug) return Astro.redirect(/404); const { entry: post, cacheHint } await getEmDashEntry(posts, slug); if (!post) return Astro.redirect(/404); Astro.cache.set(cacheHint); const seo getSeoMeta(post, { siteTitle: My Blog, siteUrl: Astro.url.origin, path: /posts/${slug}, }); const tags await getEntryTerms(posts, post.data.id, tag); --- Base title{seo.title} description{seo.description} article {post.data.featured_image ( div {...post.edit.featured_image} Image image{post.data.featured_image} / /div )} h1 {...post.edit.title}{post.data.title}/h1 PortableText value{post.data.content} / {tags.length 0 ( div {tags.map(t a href{/tag/${t.slug}}{t.label}/a)} /div )} /article /Base這里示范了三個要點getSeoMeta導(dǎo)出自 seo/index.ts根據(jù) entry 生成 SEO 標題與描述getEntryTerms(posts, post.data.id, tag)必須傳數(shù)據(jù)庫 ULIDpost.data.id而非 slug可視化編輯屬性與Image/PortableText組合使用。分類歸檔頁如/category/[slug].astro--- import { getTerm, getEmDashCollection } from emdash; import Base from ../../layouts/Base.astro; const { slug } Astro.params; const term slug ? await getTerm(category, slug) : null; if (!term) return Astro.redirect(/404); const { entries: posts } await getEmDashCollection(posts, { where: { category: term.slug }, orderBy: { published_at: desc }, }); --- Base title{${term.label} posts} h1{term.label}/h1 {posts.map(post ( a href{/posts/${post.id}}{post.data.title}/a ))} /BasegetTerm按(taxonomy, slug)取單個詞條含 label、slug、children 等并支持 locale fallback 鏈與可選的可見條目計數(shù)includeCounts: false可跳過計數(shù)查詢實現(xiàn)見 taxonomies/index.ts。歸檔頁隨后用where: { category: term.slug }過濾出該分類下的條目。RSS 源如/rss.xml.tsimport type { APIRoute } from astro; import { getEmDashCollection } from emdash; const siteTitle My Site; export const GET: APIRoute async ({ url }) { const siteUrl url.origin; const { entries: posts } await getEmDashCollection(posts, { orderBy: { published_at: desc }, limit: 20, }); const items posts .filter((p) p.data.publishedAt) .map((post) { const postUrl ${siteUrl}/posts/${post.id}; return item title${escapeXml(post.data.title)}/title link${postUrl}/link guid isPermaLinktrue${postUrl}/guid pubDate${post.data.publishedAt!.toUTCString()}/pubDate description${escapeXml(post.data.excerpt || )}/description /item; }) .join(\n); return new Response( ?xml version1.0 encodingUTF-8? rss version2.0 xmlns:atomhttp://www.w3.org/2005/Atom channel title${escapeXml(siteTitle)}/title link${siteUrl}/link atom:link href${siteUrl}/rss.xml relself typeapplication/rssxml/ languageen-us/language lastBuildDate${new Date().toUTCString()}/lastBuildDate ${items} /channel /rss, { headers: { Content-Type: application/rssxml; charsetutf-8, Cache-Control: public, max-age3600, }, }, ); }; function escapeXml(s: string): string { return s .replace(//g, amp;) .replace(//g, lt;) .replace(//g, gt;) .replace(//g, quot;) .replace(//g, apos;); }要點過濾掉未發(fā)布的條目p.data.publishedAt為 null 的過濾掉、用entry.id拼 URL、用toUTCString()輸出 RFC 822 時間并對所有動態(tài)文本做 XML 轉(zhuǎn)義。404 頁面/404.astro--- import Base from ../layouts/Base.astro; --- Base titleNot Found h1Page not found/h1 pThe page youre looking for doesnt exist./p a href/Go home/a /Base空狀態(tài)當集合還沒有內(nèi)容時展示一個友好的空狀態(tài)引導(dǎo)去后臺創(chuàng)建第一篇內(nèi)容{posts.length 0 ? ( section h2No posts yet/h2 pCreate your first post in the admin panel./p a href/_emdash/admin/content/posts/newCreate a post/a /section ) : ( /* ... render posts ... */ )}分頁cursor 與 offset 兩種方式getEmDashCollection內(nèi)置兩種互斥的分頁方式keyset 游標分頁cursor與偏移分頁offset。源碼中的類型定義保證了二者不能同時傳入同時提供在編譯期報錯見 query.ts。游標分頁推薦用于“下一頁”翻頁把上一次結(jié)果的nextCursor傳入下一次請求的cursor即可nextCursor為undefined表示沒有更多結(jié)果--- const cursor Astro.url.searchParams.get(cursor) ?? undefined; const { entries, nextCursor, cacheHint } await getEmDashCollection(posts, { limit: 10, cursor, orderBy: { published_at: desc }, }); Astro.cache.set(cacheHint); --- {entries.map(post ( a href{/posts/${post.id}}{post.data.title}/a ))} {nextCursor a href{?cursor${nextCursor}}Next page/a}游標是不透明字符串由查詢層按“排序值 數(shù)據(jù)庫 ID”編碼encodeEntryCursor見 query.ts編碼時對日期列優(yōu)先使用原始存儲字符串以避免時區(qū)/精度損耗因此翻頁穩(wěn)定、不受新插入數(shù)據(jù)影響。偏移分頁用于/page/2這類編號歸檔結(jié)果中的hasMore表示是否還有后續(xù)條目適合渲染“下一頁”鏈接而無需計算總數(shù)const perPage 20; const { entries, hasMore } await getEmDashCollection(posts, { limit: perPage, offset: (page - 1) * perPage, orderBy: { published_at: desc }, });兩種方式下只要傳了limit結(jié)果都會附帶hasMore字段默認limit 1探測法判斷見 query.ts。日期格式化查詢返回的日期字段createdAt、updatedAt、publishedAt都是Date對象直接用toLocaleDateString或Intl.DateTimeFormat格式化const formatted post.data.publishedAt?.toLocaleDateString(en-US, { year: numeric, month: long, day: numeric, });注意publishedAt可能為null未發(fā)布取值時要先判空如可選鏈?.。實戰(zhàn)要點小結(jié)所有查詢函數(shù)從emdash導(dǎo)入類型由生成到站點里的emdash-env.d.ts提供EmDashCollections接口擴展后集合名與字段自動獲得類型推斷見 query.ts拼錯集合名或字段名會得到編譯期錯誤每次查詢后都調(diào)用Astro.cache.set(cacheHint)保證內(nèi)容變更自動失效緩存URL 用entry.idslug數(shù)據(jù)庫 API如getEntryTerms用entry.data.idULIDCMS 圖片必須用Image組件傳對象不要直接src{對象}富文本用PortableText自定義 CMS 區(qū)塊通過components{{ type: {...} }}注入管理端登錄后把post.edit.*展開到元素上即獲得行內(nèi)點選編輯能力列表、詳情、歸檔、RSS、404、空狀態(tài)、分頁、日期格式化可直接復(fù)制上面的代碼模式改造到自己的站點。贊分享CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載相關(guān)推薦EmDash 內(nèi)容查詢與渲染實戰(zhàn)從 getEmDashCollection 到 Portable Text 的完整指南EmDash 內(nèi)容查詢與渲染實戰(zhàn)從 getEmDashCollection 到 Portable Text 的完整指南 這篇技術(shù)指南圍繞 EmDash 前端模CMS后端前端插件系統(tǒng)EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、Portable Text 與可視化編輯EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、Portable Text 與可視化編輯 EmDash 是一個基于 Astro 的CMS后端前端插件系統(tǒng)EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、PortableText 與常見頁面模式EmDash 內(nèi)容查詢與渲染實戰(zhàn)指南getEmDashCollection、PortableText 與常見頁面模式 導(dǎo)讀 本文基于 EmDash 官方站點構(gòu)CMS后端前端插件系統(tǒng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考