Field Kit

インストール

npmからパッケージをインストールします。

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

fieldKitPlugin をインポートして呼び出し、その結果を plugins: [] に追加します。

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": [{ "key": "name", "label": "Name", "type": "text", "required": true }]
	}
}

ウィジェット

ウィジェットに必須の options（例：object-form／list の fields、grid の rows／columns）が欠けている場合、編集画面には壊れた入力欄ではなく、インラインで「Widget misconfigured」という警告が表示されます。シードのスキーマを試行錯誤している間に役立ちます。

object-form

型を持つサブフィールドのまとまりを表示し、1つの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 }。

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

grid

行×列の2次元のマトリクスです。各セルは、トグル、テキストの入力欄、数値の入力欄、選択欄のいずれかにできます。季節ごとの入手可否、価格表、機能の比較のようなマトリクスに役立ちます。次のフィールド定義は、季節ごとの入手可否のグリッドを設定します。

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

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

<kbd>Enter</kbd>または , を押すと、タグが確定します。入力欄が空のときに<kbd>Backspace</kbd>を押すと、最後のタグが削除されます。重複するタグは、何も表示せずに無視されます。

サブフィールド

object-form と list は、型を持つサブフィールドの定義の配列を options.fields で受け付けます。各項目は、key（書き込み先のJSONオブジェクトのキー）、label、type と、型ごとの追加の項目を持ちます。

すべてのサブフィールドに共通のプロパティ：required、helpText、defaultValue。

要約のテンプレート

list ウィジェットは、折りたたんだ各行を、options.summary のMustache形式のテンプレートで描画します。{{key}} は、そのキーに対応する行の値（文字列に変換したもの）に置き換えられます。値が偽とみなされる場合は "{itemLabel} {n}" が代わりに使われます。次のテンプレートは、2つのキーを組み合わせます。

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

行は Flour — 500g のように描画されます。テンプレートは単純な文字列の置き換えで、HTMLや入れ子の式は使えません。

データの持続性

Field Kitのウィジェットは、フィールドの既存のカラムだけを使い、そこにプレーンなJSONを保存します。設定から @emdash-cms/plugin-field-kit を削除しても、データは有効なままです。フィールドは標準の json のテキスト入力欄に戻ります。

これは、ウィジェットの形を変えた場合にも当てはまります。保存済みのオブジェクトにある未知のキーは次の書き込みでも保持されるため、古いフィールドの構成で保存したデータを失わずにスキーマを変えていけます。

関連項目

• プラグイン概要：EmDashのプラグインの仕組み
• プラグイン形式の選び方：Field Kitが合わない場合に、独自のフィールドウィジェットを作る
• Discussion #571：このプラグインのきっかけになった提案