欄位類型參考

EmDash 支援 14 種欄位類型以定義內容結構描述。每種類型對應到 SQLite 欄類型，並提供適當的管理後台 UI。

Overview

Text Types

string

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

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

Validation options:

• minLength — 最少字元數
• maxLength — 最多字元數
• pattern — 需符合的正則式模式

Widget options:

• 無特定項目

text

多行純文字。用於描述、摘錄與較長純文字。

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

Validation options:

• minLength — 最少字元數
• maxLength — 最多字元數

Widget options:

• rows — textarea 列數（預設：3）

slug

URL 安全識別碼。可從其他欄位自動產生或手動輸入。

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

slug 會自動正規化：小寫、空格變連字號、移除特殊字元。

Number Types

number

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

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

Validation options:

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

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

integer

整數。用於數量、計數與排序值。

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

Validation options:

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

以 SQLite INTEGER 儲存。

boolean

真或假。用於切換與旗標。

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

以 SQLite INTEGER（0 或 1）儲存。

Date and Time

datetime

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

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

Validation options:

• min — 最早日期（ISO 字串）
• max — 最晚日期（ISO 字串）

Storage format: 2025-01-24T12:00:00.000Z

Selection Types

select

從預先定義的選項中單選。

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

Validation options:

• options — 允許值的陣列（必填）

以包含所選值的 TEXT 儲存。

multiSelect

從預先定義的選項中複選。

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

Validation options:

• options — 允許值的陣列（必填）

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

Rich Content

portableText

Portable Text 格式的豐富文字。支援標題、清單、連結、圖片與自訂區塊。

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

以 Portable Text 區塊的 JSON 陣列儲存：

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

外掛程式可向編輯器新增自訂區塊類型（嵌入、小工具等）。它們出現在斜線命令選單中，並在網站上自動算繪。請參閱 Creating Plugins — Portable Text Block Types.

Media Types

image

指向已上傳圖片的參照。包含尺寸、替代文字等詮釋資料。

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

Widget options:

• showPreview — 在後台顯示圖片預覽（預設：true）

Stored value:

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

file

指向已上傳檔案（文件、PDF 等）的參照。

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

Stored value:

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

Relational Types

reference

指向另一筆內容項目的參照。

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

Widget options:

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

Single reference stored value:

"01HXK5MZSN..."

Multiple references stored value:

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

Flexible Types

json

任意 JSON 資料。用於巢狀結構、第三方整合或無固定結構描述的資料。

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

原樣儲存在 SQLite JSON 欄中。

Field Properties

所有欄位都支援下列通用屬性：

Reserved Field Slugs

下列 slug 已保留，無法使用：

• id
• slug
• status
• author_id
• created_at
• updated_at
• published_at
• deleted_at
• version

TypeScript Types

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

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

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