E EmDash CMS Everything Guides, use cases, plugins, templates
繁體中文

Field Kit

本頁內容

EmDash 的 json 欄位類型儲存任意結構化資料，預設透過接受原始 JSON 的單行文字輸入進行編輯。Field Kit 是一個官方外掛程式，為 json 欄位提供四個可組合的小工具，完全透過 seed options 進行配置，因此網站建構者可以僅使用 seed schema 來使用它們。

安裝

從 npm 安裝套件：

npm i @emdash-cms/plugin-field-kit

以下配置註冊外掛程式：

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { fieldKitPlugin } from "@emdash-cms/plugin-field-kit";

export default defineConfig({
	integrations: [
		emdash({
			plugins: [fieldKitPlugin()],
		}),
	],
});

透過將 widget 設定為 field-kit:<name> 來將小工具附加到任何 json 欄位。以下欄位定義使用 list 小工具：

{
	"slug": "ingredients",
	"type": "json",
	"widget": "field-kit:list",
	"options": { "fields": [...] }
}

小工具

小工具用途儲存的值
object-form扁平 JSON 物件的內聯表單{ key: value, ... }
list帶有新增/移除/重新排序的有序陣列編輯器[{ ... }, ...]
grid列×欄矩陣{ rowKey: { colKey: value } }
tags自由形式的晶片/標籤輸入["tag1", "tag2"]

如果小工具缺少其必需的 options（例如 object-form/list 的 fields，或 grid 的 rows/columns），編輯器會呈現內聯「小工具配置錯誤」警告，而不是損壞的輸入 — 在迭代 seed schema 時很有用。

object-form

呈現作為單個 JSON 物件儲存的類型化子欄位組。適用於固定形狀的結構化資料，如營養資訊或聯絡資訊。以下欄位定義配置營養物件：

{
	"slug": "nutrition",
	"type": "json",
	"widget": "field-kit:object-form",
	"options": {
		"collapsed": false,
		"fields": [
			{ "key": "calories", "label": "Calories", "type": "number", "suffix": "kcal" },
			{ "key": "protein", "label": "Protein", "type": "number", "suffix": "g" },
			{ "key": "fat", "label": "Fat", "type": "number", "suffix": "g" },
			{ "key": "carbs", "label": "Carbs", "type": "number", "suffix": "g" }
		]
	}
}

儲存的值：{ "calories": 250, "protein": 12.5, "fat": 8, "carbs": 30 }。

選項類型預設值說明
fieldsSubFieldDef[]（必需）子欄位定義 — 請參閱子欄位。
collapsedbooleanfalse預設摺疊群組。
helpTextstring—顯示在小工具下方的說明文字。

list

具有新增、移除和重新排序控制項的有序陣列編輯器。每列是一個 JSON 物件，其形狀由 fields 定義。列標題顯示從 Mustache 樣式範本呈現的摘要。以下欄位定義配置成分清單：

{
	"slug": "ingredients",
	"type": "json",
	"widget": "field-kit:list",
	"options": {
		"itemLabel": "Ingredient",
		"min": 1,
		"max": 50,
		"sortable": true,
		"summary": "{{name}} — {{amount}}",
		"fields": [
			{ "key": "name", "label": "Name", "type": "text", "required": true },
			{ "key": "amount", "label": "Amount", "type": "text" },
			{ "key": "optional", "label": "Optional", "type": "boolean" }
		]
	}
}

儲存的值是列物件陣列：

[
	{ "name": "Flour", "amount": "500g", "optional": false },
	{ "name": "Butter", "amount": "200g", "optional": false }
]
選項類型預設值說明
fieldsSubFieldDef[]（必需）每列的子欄位定義。
itemLabelstring"Item"列的單數標籤（用於「新增」按鈕和備援列標題）。
minnumber—最小項目數。低於此數字時，移除按鈕隱藏。
maxnumber—最大項目數。達到此計數時，新增按鈕隱藏。
sortablebooleantrue顯示上/下重新排序按鈕。
summarystring—作為摺疊列標題呈現的 Mustache 範本。請參閱摘要範本。
helpTextstring—顯示在小工具下方的說明文字。

grid

列×欄的二維矩陣。每個儲存格可以是切換、文字輸入、數字輸入或選擇。適用於季節性可用性、價格表或功能比較等矩陣。以下欄位定義配置季節性可用性網格：

{
	"slug": "availability",
	"type": "json",
	"widget": "field-kit:grid",
	"options": {
		"cell": "toggle",
		"rows": [
			{ "key": "berries", "label": "Berries" },
			{ "key": "stoneFruit", "label": "Stone fruit" },
			{ "key": "citrus", "label": "Citrus" }
		],
		"columns": [
			{ "key": "spring", "label": "Spring" },
			{ "key": "summer", "label": "Summer" },
			{ "key": "autumn", "label": "Autumn" },
			{ "key": "winter", "label": "Winter" }
		]
	}
}

儲存的值是按列鍵入，然後按欄鍵入的物件：

{
	"berries": { "spring": false, "summer": true, "autumn": false, "winter": false },
	"stoneFruit": { "spring": false, "summer": true, "autumn": true, "winter": false },
	"citrus": { "spring": false, "summer": false, "autumn": true, "winter": true }
}
選項類型預設值說明
rowsGridAxisDef[]（必需）列定義：{ key, label, image? }。
columnsGridAxisDef[]（必需）欄定義：{ key, label, image? }。
cell"toggle" | "text" | "number" | "select""toggle"儲存格輸入類型，統一應用於每個儲存格。
cellOptionsstring[] | Array<{ label, value }>[]當 cell 為 "select" 時必需。
helpTextstring—顯示在小工具下方的說明文字。

tags

字串陣列的晶片樣式輸入。支援固定的 suggestions 清單、自由形式的自訂值（可切換）、大小寫轉換和可選的 max。以下欄位定義配置關鍵字標籤輸入：

{
	"slug": "keywords",
	"type": "json",
	"widget": "field-kit:tags",
	"options": {
		"placeholder": "Add a keyword…",
		"max": 10,
		"transform": "lowercase",
		"allowCustom": true,
		"suggestions": ["vegan", "vegetarian", "gluten-free", "dairy-free", "nut-free"]
	}
}

儲存的值：["vegan", "gluten-free"]。

按 Enter 或 , 提交標籤。在空輸入上按 Backspace 刪除最後一個標籤。重複的標籤會被靜默忽略。

選項類型預設值說明
placeholderstring"Add..."沒有標籤時顯示的輸入佔位符。
maxnumber—最大標籤數。達到限制時輸入隱藏。
suggestionsstring[][]透過 <datalist> 顯示的自動完成建議。
allowCustombooleantrue當為 false 時，只能新增 suggestions 中的值。
transform"none" | "lowercase" | "uppercase" | "trim""none"在新增標籤時對其進行規範化。
helpTextstring—顯示在小工具下方的說明文字。

子欄位

object-form 和 list 接受類型化子欄位定義的 options.fields 陣列。每個條目都有一個 key（它寫入的 JSON 物件鍵）、一個 label、一個 type 和類型特定的額外項。

子欄位類型呈現為值得注意的額外項
text單行輸入placeholder
textarea多行輸入rows（預設 3）、placeholder
number數字輸入min、max、step、prefix、suffix、placeholder
boolean切換開關—
select下拉式選單options: string[] | Array<{ label, value }>、placeholder
date日期輸入—
color與十六進位文字輸入配對的原生顏色選擇器—
urlURL 輸入（HTML5 type="url"）placeholder

每個子欄位的通用屬性：required、helpText、defaultValue。

摘要範本

list 小工具使用 options.summary 中的 Mustache 樣式範本呈現每個摺疊的列。{{key}} 被替換為該鍵的列值（強制轉換為字串）。假值回退到 "{itemLabel} {n}"。以下範本組合兩個鍵：

"summary": "{{name}} — {{amount}}"

呈現如 Flour — 500g 的列。範本是簡單的字串替換 — 沒有 HTML，沒有巢狀運算式。

資料持久性

Field Kit 小工具將純 JSON 儲存在欄位的現有欄中，僅使用該欄。如果從配置中移除 @emdash-cms/plugin-field-kit，資料仍然有效 — 欄位恢復為預設的 json 文字輸入。

即使變更小工具形狀，這也適用：儲存物件上的未知鍵在下次寫入時會被保留，因此您可以在不遺失在較舊欄位集下擷取的資料的情況下演化 schema。

另請參閱