欄位類型參考 | EmDash CMS Everything

EmDash 支援 17 種用於定義內容模式的欄位類型。每種類型對應一個 SQLite 欄類型，並提供相應的管理 UI。

概覽

下表列出每種欄位類型及其 SQLite 欄：

Type	SQLite Column	Description
`string`	TEXT	短文字輸入
`text`	TEXT	多行文字
`url`	TEXT	URL 值
`number`	REAL	小數
`integer`	INTEGER	整數
`boolean`	INTEGER	真/假
`datetime`	TEXT	日期與時間
`select`	TEXT	從選項中單選
`multiSelect`	JSON	多選
`portableText`	JSON	富文字內容
`image`	TEXT	圖片參照
`file`	TEXT	檔案參照
`reference`	none	連結到另一集合中的項目
`json`	JSON	任意 JSON 資料
`slug`	TEXT	URL 安全識別碼
`repeater`	JSON	可重複欄位群組
`blocks`	JSON	型別化頁面組合

文字類型

`string`

短單行文字。用於標題、名稱和短值。

{
  slug: "title",
  label: "Title",
  type: "string",
  required: true,
  validation: {
    minLength: 1,
    maxLength: 200,
  },
}

驗證選項：

minLength — 最小字元數
maxLength — 最大字元數
pattern — 值必須符合的正規表示式

編輯器將輸入限制為 maxLength，並對照長度規則顯示即時字元計數。

小組件選項：

無特定選項

`text`

多行純文字。用於描述、摘要和較長的純文字。

{
  slug: "excerpt",
  label: "Excerpt",
  type: "text",
  options: {
    rows: 3,
  },
}

驗證選項：

minLength — 最小字元數
maxLength — 最大字元數
pattern — 值必須符合的正規表示式

編輯器將輸入限制為 maxLength，並對照長度規則顯示即時字元計數。

小組件選項：

rows — 文字區域行數（預設：3）

`url`

網址。內容 API 會拒絕不是有效 URL 的值。

{
  slug: "website",
  label: "Website",
  type: "url",
  required: true,
}

URL 欄位以文字形式儲存。當值可能是相對路徑（如 /about）時，請改用 string 欄位，因為相對路徑不是 url 欄位的有效值。

`slug`

用於保存類似 slug 值的文字。此自訂欄位類型不會產生或清理其值。

{
  slug: "legacy_slug",
  label: "Legacy Slug",
  type: "slug",
  required: true,
  unique: true,
}

每個內容項目都已有一個保留的系統 slug，由 EmDash 單獨管理用於公開 URL。僅當內容模型需要另一個已儲存的類似 slug 值時，才使用自訂 slug 欄位。

數字類型

`number`

小數。用於價格、評分和度量。

{
  slug: "price",
  label: "Price",
  type: "number",
  required: true,
  validation: {
    min: 0,
    max: 999999.99,
  },
}

驗證選項：

min — 最小值
max — 最大值

編輯器在數字輸入上設定 min 和 max，並在下方顯示允許範圍。

儲存為 SQLite REAL（64 位元浮點）。

`integer`

整數。用於數量、計數和順序值。

{
  slug: "quantity",
  label: "Quantity",
  type: "integer",
  defaultValue: 1,
  validation: {
    min: 0,
    max: 1000,
  },
}

驗證選項：

min — 最小值
max — 最大值

編輯器在數字輸入上設定 min 和 max，並在下方顯示允許範圍。

儲存為 SQLite INTEGER。

`boolean`

真或假。用於開關和旗標。

{
  slug: "featured",
  label: "Featured",
  type: "boolean",
  defaultValue: false,
}

儲存為 SQLite INTEGER（0 或 1）。

日期與時間

`datetime`

時間上的一個瞬間。API、MCP 和 CLI 寫入必須包含 Z 或明確 UTC 偏移。管理端在 Settings → General 設定的時區中解譯其日期時間選擇器。

{
  slug: "publishedAt",
  label: "Published At",
  type: "datetime",
}

儲存格式： 2025-01-24T12:00:00.000Z

EmDash 在儲存前將接受的輸入轉換為帶三位毫秒的 UTC。例如，2025-01-24T21:00:00+09:00 儲存為 2025-01-24T12:00:00.000Z。當值是日曆日期或本地掛鐘時間而非瞬間時，請改用 string 欄位。

選擇類型

`select`

從預定義選項中單選。

{
  slug: "status",
  label: "Status",
  type: "select",
  required: true,
  defaultValue: "draft",
  validation: {
    options: ["draft", "published", "archived"],
  },
}

驗證選項：

options — 可選的允許值陣列。提供它以展示預定義選項並拒絕其他字串；不提供時，驗證接受任意字串。

儲存為包含所選值的 TEXT。

`multiSelect`

從預定義選項中多選。

{
  slug: "tags",
  label: "Tags",
  type: "multiSelect",
  validation: {
    options: ["news", "tutorial", "review", "opinion"],
  },
}

驗證選項：

options — 可選的允許值陣列。提供它以展示預定義選項並拒絕其他字串；不提供時，驗證接受任意字串陣列。

儲存為 JSON 陣列：["news", "tutorial"]

富內容

`portableText`

使用 Portable Text 格式的富文字內容。支援標題、清單、連結、圖片和自訂區塊。

{
  slug: "content",
  label: "Content",
  type: "portableText",
  required: true,
}

值儲存為 Portable Text 區塊的 JSON 陣列，例如：

[
	{
		"_type": "block",
		"style": "normal",
		"children": [{ "_type": "span", "text": "Hello world" }]
	}
]

外掛可以向編輯器新增自訂區塊類型（嵌入、小組件等）。它們出現在斜線命令選單中。在公開網站上渲染已儲存的區塊需要來自原生外掛或配套套件的 Astro 元件。參見 Portable Text 渲染元件。

媒體類型

`image`

對已上傳圖片的參照。包含尺寸和替代文字等中繼資料。

{
  slug: "featuredImage",
  label: "Featured Image",
  type: "image",
  validation: {
    allowedMimeTypes: ["image/jpeg", "image/png"],
  },
  options: {
    darkVariant: true,
  },
}

小組件選項：

darkVariant — 為編輯者提供第二個插槽，用於在深色配色方案中顯示的圖片（預設：false）。參見 Dark Mode。

驗證選項：

allowedMimeTypes — 所選媒體接受的精確 MIME 類型的非空清單

值儲存為帶有媒體參照及其中繼資料的物件：

{
	"id": "01HXK5MZSN...",
	"src": "/_emdash/api/media/file/01HXK5MZSN...",
	"alt": "Description",
	"width": 1920,
	"height": 1080,
	"provider": "local",
	"meta": {
		"storageKey": "01HXK5MZSN....jpg"
	}
}

啟用 darkVariant 時，值可以在 darkVariant 下攜帶相同形狀的深色對應項：

{
	"id": "01HXK5MZSN...",
	"alt": "Architecture diagram",
	"width": 1920,
	"height": 1080,
	"darkVariant": {
		"id": "01HXK5N2QT...",
		"width": 1920,
		"height": 1080
	}
}

`file`

對已上傳檔案（如文件或 PDF）的參照。

{
  slug: "document",
  label: "Document",
  type: "file",
  validation: {
    allowedMimeTypes: ["application/pdf"],
  },
}

驗證選項：

allowedMimeTypes — 所選媒體接受的精確 MIME 類型的非空清單

值儲存為帶有快取中繼資料的提供者參照：

{
	"id": "01HXK5MZSN...",
	"provider": "local",
	"filename": "report.pdf",
	"mimeType": "application/pdf",
	"meta": {
		"storageKey": "01HXK5MZSN....pdf"
	}
}

url 和 size 與其他快取中繼資料欄位一樣是可選的。內容查詢依原樣回傳持久化值，不會從媒體庫水合。需要最新中繼資料或提供者特定 URL 時，參見檔案值與目前中繼資料了解規範查詢 API。

關係類型

`reference`

將項目連結到另一集合中的項目，並在管理端渲染為項目選擇器。其連結屬於一個關係：一個連接兩個集合、為每一側命名並限制每一側可連結多少項目的模式物件。Relations 涵蓋編輯者與管理端工作流程。

以下欄位將一篇文章連結到 authors 集合中的一個項目：

{
  slug: "author",
  label: "Author",
  type: "reference",
  required: true,
  validation: {
    targetCollection: "authors",
    multiple: false,
  },
}

驗證：

targetCollection — 此欄位連結到的集合的 slug。建立欄位會為其建立關係。
multiple — 允許連結多個項目（預設：false）。僅與 targetCollection 一起閱讀，因為限制隨後屬於新關係。
relation — 要繫結到的現有關係的 slug，而不是建立新關係。
relationSide — 此集合位於 relation 的哪一端，"parent" 或 "child"。僅對兩端為同一集合且兩端相符的關係設定。

提供 targetCollection 或 relation 之一。從 targetCollection 建立的欄位成為名為 {collection}_{field} 的關係的父端，其子側採用欄位的標籤，並且除非設定了 multiple，否則持有一個項目。從 relation 建立的欄位從其所在集合的那一端檢視該關係，另一端的集合是欄位的目標。一個關係每一端只接受一個欄位，因此同一端上的第二個欄位會被拒絕。兩種形式都在已建立的欄位上儲存 relation、relationSide 和 targetCollection，並且目標集合此後固定：要變更它，請刪除欄位並新增欄位。重新命名欄位會重新命名它所檢視的關係那一側。

參照欄位不會向集合資料表新增欄。其連結位於 _emdash_content_references 中，按每個項目的翻譯群組鍵控，因此選擇在項目的翻譯之間共用，而不是按語地區設定。內容讀取在按欄位 slug 鍵控的 references 下回傳連結的項目，而不是在 data 中。在範本中按名稱請求欄位 — 參見讀取參照欄位。

繫結到關係的欄位不能設定 indexed，因為它不儲存可索引的欄，並且網站搜尋也不涵蓋它。

無關係的欄位

既不指定關係也不指定目標集合的參照欄位保留 TEXT 欄，並在其中保存一個項目 ID：

"01HXK5MZSN..."

設定了 options.allowMultiple 的欄位在同一欄中保存項目 ID 的 JSON 陣列：

["01HXK5MZSN...", "01HXK6NATS..."]

該欄像任何其他文字欄一樣讀寫，集合模式將值驗證為字串，並且欄位可以設定 indexed 並充當內容清單篩選器。它渲染為文字方塊而不是選擇器。

要將其變為選擇器，在 Content Types 下開啟該欄位並選擇一個被參照的集合。 EmDash 建立關係，將欄中的項目 ID 複製為連結，並清除欄位的 searchable 和 indexed 旗標，因此內容清單篩選器和網站搜尋不再涵蓋它。欄仍留在原處並停止寫入。Relations 從編輯者一側涵蓋相同步驟。

從較早版本更新的網站可能保留此狀態的欄位。參見參照欄位繫結到關係了解更新繫結了什麼以及留給你繫結什麼。

彈性類型

`json`

任意 JSON 資料。用於複雜巢狀結構、第三方整合或沒有固定模式的資料。

{
  slug: "metadata",
  label: "Metadata",
  type: "json",
}

依原樣儲存在 SQLite JSON 欄中。

`repeater`

結構化列的可重複清單。在 validation.subFields 中至少定義一個子欄位；編輯者隨後可以新增、移除、重新排序和編輯列，而無需輸入原始 JSON。

以下欄位儲存產品規格清單：

{
  slug: "specifications",
  label: "Specifications",
  type: "repeater",
  validation: {
    minItems: 1,
    maxItems: 12,
    subFields: [
      { slug: "label", label: "Label", type: "string", required: true },
      { slug: "value", label: "Value", type: "text", required: true },
      { slug: "source", label: "Source", type: "url" },
    ],
  },
}

Repeater 值儲存為物件陣列：

[
	{
		"label": "Weight",
		"value": "1.2 kg",
		"source": "https://example.com/specifications"
	}
]

允許的子欄位類型為 string、text、url、number、integer、boolean、datetime、select 和 image。Repeater 不能包含另一個 repeater 或 portableText、reference、file 等複雜欄位。

Repeater 驗證接受這些屬性：

subFields — 一個或多個子欄位定義。每個定義需要 slug、label 和 type；也可以設定 required。select 子欄位透過 options 提供其選項。
minItems — 最小列數。必須為零或更大。
maxItems — 最大列數。必須為一或更大，且不能小於 minItems。

`blocks`

型別化內容區塊的有序清單。每種區塊類型有自己的欄位並保留編號版本。在將它們新增到集合欄位之前，透過模式 API、MCP 或種子檔案定義區塊類型。

以下欄位允許編輯者用英雄區和行動號召區塊組合頁面：

{
  slug: "layout",
  label: "Layout",
  type: "blocks",
  validation: {
    allowedTypes: ["hero", "call_to_action"],
    maxItems: 20,
  },
}

每個已儲存的區塊在該版本宣告的欄位旁攜帶其類型、版本和穩定鍵：

[
	{
		"_type": "hero",
		"_version": 1,
		"_key": "01K5AB3F7M9QZ2X8W4V6T1R0YH",
		"heading": "Bread made slowly, by hand."
	}
]

Blocks 驗證接受這些屬性：

allowedTypes — 可供新區塊使用的有序區塊類型 slug。
retiredTypes — 為已儲存內容保留但對新區塊不可用的伺服器管理區塊類型。
minItems — 最小區塊數。在已有資料的集合上將其提高到零以上需要內容遷移。
maxItems — 最大區塊數，最多 100。

blocks 欄位是可選的，預設為空陣列。它不能為 required、unique、searchable、indexed，也不能由自訂欄位小組件渲染。區塊定義可以使用純量、文字、選擇、Portable Text、圖片、檔案和 repeater 欄位。它們不能包含參照、JSON、slug 或巢狀 blocks。

用 emdash/ui 的 <Blocks value components fallback> 渲染已儲存的陣列。種子、元件對應、缺失渲染器、啟用和遷移範例見用 blocks 建置頁面。

欄位屬性

所有欄位都支援這些通用屬性：

Property	Type	Description
`slug`	`string`	唯一識別碼（必要）
`label`	`string`	顯示名稱（必要）
`type`	`FieldType`	欄位類型（必要）
`required`	`boolean`	要求有值（預設：false）
`unique`	`boolean`	強制唯一性（預設：false）
`searchable`	`boolean`	將欄位納入全文搜尋（預設：false）
`indexed`	`boolean`	啟用索引排序/篩選
`translatable`	`boolean`	按語地區儲存值（預設：true）
`defaultValue`	`unknown`	新項目的預設值
`validation`	`object`	類型特定的驗證規則
`widget`	`string`	自訂小組件覆寫
`options`	`object`	小組件設定
`sortOrder`	`number`	管理端中的顯示順序

indexed 可用於純量欄位：string、url、number、integer、boolean、 datetime、select、reference 和 slug。索引欄位可作為內容清單查詢中的 orderBy 欄位傳遞，或用於 fieldFilters。避免索引不用於排序或篩選的欄位，因為每個索引都會增加儲存和寫入開銷。

searchable 將欄位的文字新增到集合的全文搜尋索引。對識別碼、價格、旗標以及其他必須在項目的每次翻譯中保持相同的值設定 translatable: false；當某個語地區變更不可翻譯欄位時，EmDash 會將該值同步到其翻譯項目。

blocks 類型僅使用此通用集合中的 slug、label、type、translatable、validation 和 sortOrder。其陣列從不作為欄必要，並且始終預設為 []。

保留的欄位 slug

這些 slug 已保留，不能使用：

id
slug
status
author_id
primary_byline_id
created_at
updated_at
published_at
scheduled_at
deleted_at
version
live_revision_id
draft_revision_id
terms
bylines
byline

TypeScript 類型

匯入欄位類型定義以供程式化使用：

import type { FieldType, Field, CreateFieldInput } from "emdash";

const fieldTypes: FieldType[] = [
	"string",
	"text",
	"url",
	"number",
	"integer",
	"boolean",
	"datetime",
	"select",
	"multiSelect",
	"portableText",
	"image",
	"file",
	"reference",
	"json",
	"slug",
	"repeater",
	"blocks",
];