Field Kit

EmDashs json-Feldtyp speichert beliebige strukturierte Daten, die standardmäßig über ein einzeiliges Texteingabefeld bearbeitet werden, das rohes JSON akzeptiert. Field Kit ist ein offizielles Plugin, das vier zusammensetzbare Widgets für json-Felder bereitstellt, die vollständig über Seed-options konfiguriert werden, sodass Site-Builder sie allein mit dem Seed-Schema verwenden können.

Installation

Installieren Sie das Paket von npm:

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

Die folgende Konfiguration registriert das Plugin:

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()],
		}),
	],
});

Hängen Sie ein Widget an ein beliebiges json-Feld an, indem Sie widget auf field-kit:<name> setzen. Die folgende Felddefinition verwendet das list-Widget:

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

Widgets

Wenn einem Widget seine erforderlichen options fehlen (z. B. fields für object-form/list oder rows/columns für grid), rendert der Editor eine Inline-Warnung “Widget falsch konfiguriert” anstelle einer defekten Eingabe – nützlich beim Iterieren über Seed-Schemas.

object-form

Rendert eine Gruppe von typisierten Unterfeldern, die als einzelnes JSON-Objekt gespeichert werden. Gut für strukturierte Daten mit fester Form wie Nährwertangaben oder Kontaktinformationen. Die folgende Felddefinition konfiguriert ein Nährwertobjekt:

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

Gespeicherter Wert: { "calories": 250, "protein": 12.5, "fat": 8, "carbs": 30 }.

list

Ein geordneter Array-Editor mit Hinzufügen-, Entfernen- und Neuordnen-Steuerungen. Jede Zeile ist ein JSON-Objekt, dessen Form durch fields definiert wird. Der Zeilenkopf zeigt eine Zusammenfassung, die aus einer Mustache-ähnlichen Vorlage gerendert wird. Die folgende Felddefinition konfiguriert eine Zutatenliste:

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

Der gespeicherte Wert ist ein Array von Zeilenobjekten:

[
	{ "name": "Flour", "amount": "500g", "optional": false },
	{ "name": "Butter", "amount": "200g", "optional": false }
]

grid

Eine zweidimensionale Matrix aus Zeilen × Spalten. Jede Zelle kann ein Schalter, Texteingabe, Zahleneingabe oder Auswahl sein. Nützlich für Matrizen wie saisonale Verfügbarkeit, Preistabellen oder Funktionsvergleiche. Die folgende Felddefinition konfiguriert ein Gitter für saisonale Verfügbarkeit:

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

Der gespeicherte Wert ist ein Objekt, das nach Zeile und dann nach Spalte indiziert ist:

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

Eine Chip-artige Eingabe für String-Arrays. Unterstützt eine feste suggestions-Liste, freiformige benutzerdefinierte Werte (umschaltbar), Groß-/Kleinschreibungsumwandlungen und ein optionales max. Die folgende Felddefinition konfiguriert eine Schlüsselwort-Tag-Eingabe:

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

Gespeicherter Wert: ["vegan", "gluten-free"].

Drücken Sie Enter oder ,, um ein Tag zu bestätigen. Backspace bei leerer Eingabe entfernt das letzte Tag. Doppelte Tags werden stillschweigend ignoriert.

Unterfelder

object-form und list akzeptieren ein options.fields-Array von typisierten Unterfeld-Definitionen. Jeder Eintrag hat einen key (den JSON-Objektschlüssel, in den geschrieben wird), ein label, einen type und typspezifische Extras.

Gemeinsame Eigenschaften für jedes Unterfeld: required, helpText, defaultValue.

Zusammenfassungsvorlagen

Das list-Widget rendert jede eingeklappte Zeile mit einer Mustache-ähnlichen Vorlage in options.summary. {{key}} wird durch den Zeilenwert für diesen Schlüssel ersetzt (zu einem String konvertiert). Falsche Werte fallen auf "{itemLabel} {n}" zurück. Die folgende Vorlage kombiniert zwei Schlüssel:

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

Rendert Zeilen wie Flour — 500g. Die Vorlage ist einfache String-Substitution – kein HTML, keine verschachtelten Ausdrücke.

Datenbeständigkeit

Field Kit-Widgets speichern einfaches JSON in der vorhandenen Spalte des Feldes und verwenden nur diese Spalte. Wenn Sie @emdash-cms/plugin-field-kit aus Ihrer Konfiguration entfernen, bleiben die Daten gültig – das Feld kehrt zur Standard-json-Texteingabe zurück.

Dies gilt auch, wenn Sie die Widget-Form ändern: Unbekannte Schlüssel bei gespeicherten Objekten werden beim nächsten Schreibvorgang beibehalten, sodass Sie ein Schema weiterentwickeln können, ohne unter einem älteren Feldsatz erfasste Daten zu verlieren.

Siehe auch

• Plugin-Übersicht — wie EmDash-Plugins funktionieren.
• Auswahl eines Plugin-Formats — schreiben Sie Ihre eigenen Feld-Widgets, wenn Field Kit nicht passt.
• Diskussion #571 — der Vorschlag, der zu diesem Plugin führte.