Field Kit

EmDashのjsonフィールドタイプは、任意の構造化データを保存し、デフォルトでは生のJSONを受け取る単一行のテキスト入力で編集されます。Field Kitは、jsonフィールド用に4つのコンポーザブルなウィジェットを提供する公式プラグインで、シードoptionsを通じて完全に設定されるため、サイトビルダーはシードスキーマだけでこれらを使用できます。

インストール

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": [...] }
}

ウィジェット

ウィジェットに必要なoptionsが不足している場合（例：object-form/listのfields、またはgridのrows/columns）、エディタは壊れた入力の代わりにインラインで「ウィジェットが正しく設定されていません」という警告を表示します — シードスキーマを反復処理する際に便利です。

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

list

追加、削除、並べ替えコントロールを持つ順序付き配列エディタ。各行はfieldsによって形状が定義されたJSONオブジェクトです。行ヘッダーは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"]。

Enterまたは,を押してタグをコミットします。空の入力でBackspaceを押すと最後のタグが削除されます。重複するタグは黙って無視されます。

サブフィールド

object-formとlistは、型付きサブフィールド定義のoptions.fields配列を受け入れます。各エントリには、key（書き込み先のJSONオブジェクトキー）、label、type、および型固有の追加項目があります。

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

サマリーテンプレート

listウィジェットは、options.summaryのMustache形式のテンプレートを使用して、折りたたまれた各行をレンダリングします。{{key}}は、そのキーの行の値（文字列に変換）に置き換えられます。Falsy値は"{itemLabel} {n}"にフォールバックします。次のテンプレートは2つのキーを組み合わせます：

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

Flour — 500gのような行をレンダリングします。テンプレートは単純な文字列置換です — HTML、ネストされた式はありません。

データの耐久性

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

これは、ウィジェットの形状を変更した場合にも適用されます：保存されたオブジェクトの未知のキーは次の書き込み時に保持されるため、古いフィールドセットの下でキャプチャされたデータを失うことなくスキーマを進化させることができます。

関連項目

• プラグインの概要 — EmDashプラグインの仕組み。
• プラグインフォーマットの選択 — Field Kitが適合しない場合は、独自のフィールドウィジェットを作成してください。
• ディスカッション #571 — このプラグインにつながった提案。