欄位類型參考

EmDash 支援 16 種欄位類型來定義內容模式。每種類型都對應到 SQLite 欄位類型，並提供相應的管理介面。

概述

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

文字類型

string

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

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

驗證選項：

• minLength — 最小字元數
• maxLength — 最大字元數
• pattern — 要符合的正規表達式模式

小工具選項：

• 無特定選項

text

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

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

驗證選項：

• minLength — 最小字元數
• maxLength — 最大字元數

小工具選項：

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

slug

URL 安全識別碼。從另一個欄位自動產生或手動輸入。

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

Slug 會自動清理：小寫，空格替換為連字號，特殊字元移除。

數字類型

number

十進位數。用於價格、評分和測量值。

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

驗證選項：

• min — 最小值
• max — 最大值

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

integer

整數。用於數量、計數和訂單值。

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

驗證選項：

• min — 最小值
• max — 最大值

儲存為 SQLite INTEGER。

boolean

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

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

儲存為 SQLite INTEGER（0 或 1）。

日期和時間

datetime

日期和時間值。以 ISO 8601 格式儲存。

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

驗證選項：

• min — 最小日期（ISO 字串）
• max — 最大日期（ISO 字串）

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

選擇類型

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" }]
	}
]

外掛程式可以向編輯器新增自訂區塊類型（嵌入、小工具等）。這些會出現在斜線命令選單中，並在網站上自動呈現。參見 Portable Text 渲染元件。

媒體類型

image

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

{
  slug: "featuredImage",
  label: "Featured Image",
  type: "image",
  options: {
    showPreview: true,
  },
}

小工具選項：

• showPreview — 在管理介面中顯示圖片預覽（預設：true）

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

{
	"id": "01HXK5MZSN...",
	"url": "https://cdn.example.com/image.jpg",
	"alt": "Description",
	"width": 1920,
	"height": 1080
}

file

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

{
  slug: "document",
  label: "Document",
  type: "file",
}

值儲存為包含檔案參照及其中繼資料的物件：

{
	"id": "01HXK5MZSN...",
	"url": "https://cdn.example.com/doc.pdf",
	"filename": "report.pdf",
	"mimeType": "application/pdf",
	"size": 102400
}

關係類型

reference

對另一個內容項目的參照。

{
  slug: "author",
  label: "Author",
  type: "reference",
  required: true,
  options: {
    collection: "authors",
  },
}

小工具選項：

• collection — 目標集合 slug（必需）
• allowMultiple — 允許多個參照（預設：false）

單個參照儲存為目標項目 ID：

"01HXK5MZSN..."

多個參照儲存為項目 ID 陣列：

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

靈活類型

json

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

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

原樣儲存在 SQLite JSON 欄位中。

欄位屬性

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

保留欄位 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",
];