Field Kit

Il tipo di campo json di EmDash memorizza dati strutturati arbitrari, modificati per impostazione predefinita tramite un input di testo a riga singola che accetta JSON grezzo. Field Kit è un plugin ufficiale che fornisce quattro widget componibili per campi json, configurati interamente tramite options di seed in modo che i costruttori di siti possano usarli solo con lo schema seed.

Installazione

Installa il pacchetto da npm:

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

La seguente configurazione registra il 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()],
		}),
	],
});

Collega un widget a qualsiasi campo json impostando widget su field-kit:<name>. La seguente definizione di campo utilizza il widget list:

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

Widget

Se a un widget mancano le sue options richieste (ad es. fields per object-form/list, o rows/columns per grid), l’editor visualizza un avviso inline “Widget mal configurato” invece di un input rotto — utile durante l’iterazione sugli schemi seed.

object-form

Visualizza un gruppo di sotto-campi tipizzati che vengono memorizzati come singolo oggetto JSON. Buono per dati strutturati di forma fissa come informazioni nutrizionali o di contatto. La seguente definizione di campo configura un oggetto nutrizionale:

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

Valore memorizzato: { "calories": 250, "protein": 12.5, "fat": 8, "carbs": 30 }.

list

Un editor di array ordinato con controlli di aggiunta, rimozione e riordino. Ogni riga è un oggetto JSON la cui forma è definita da fields. L’intestazione della riga mostra un riepilogo visualizzato da un template stile Mustache. La seguente definizione di campo configura un elenco di ingredienti:

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

Il valore memorizzato è un array di oggetti riga:

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

grid

Una matrice bidimensionale di righe × colonne. Ogni cella può essere un interruttore, input di testo, input numerico o selezione. Utile per matrici come disponibilità stagionale, tabelle dei prezzi o confronti di funzionalità. La seguente definizione di campo configura una griglia di disponibilità stagionale:

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

Il valore memorizzato è un oggetto indicizzato per riga, poi per colonna:

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

Un input in stile chip per array di stringhe. Supporta un elenco fisso di suggestions, valori personalizzati in forma libera (attivabili), trasformazioni di maiuscole/minuscole e un max opzionale. La seguente definizione di campo configura un input di tag di parole chiave:

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

Valore memorizzato: ["vegan", "gluten-free"].

Premi Enter o , per confermare un tag. Backspace su un input vuoto rimuove l’ultimo tag. I tag duplicati vengono ignorati silenziosamente.

Sotto-campi

object-form e list accettano un array options.fields di definizioni di sotto-campi tipizzati. Ogni voce ha una key (la chiave dell’oggetto JSON in cui scrive), un label, un type e extra specifici del tipo.

Proprietà comuni su ogni sotto-campo: required, helpText, defaultValue.

Template di riepilogo

Il widget list visualizza ogni riga compressa usando un template stile Mustache in options.summary. {{key}} viene sostituito con il valore della riga per quella chiave (convertito in stringa). I valori falsi ritornano a "{itemLabel} {n}". Il seguente template combina due chiavi:

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

Visualizza righe come Flour — 500g. Il template è una semplice sostituzione di stringhe — nessun HTML, nessuna espressione annidata.

Durabilità dei dati

I widget Field Kit memorizzano JSON semplice nella colonna esistente del campo, usando solo quella colonna. Se rimuovi @emdash-cms/plugin-field-kit dalla tua configurazione, i dati rimangono validi — il campo ritorna all’input di testo json predefinito.

Questo vale anche quando si modifica la forma del widget: le chiavi sconosciute sugli oggetti memorizzati vengono preservate alla scrittura successiva, quindi puoi evolvere uno schema senza perdere i dati catturati sotto un set di campi più vecchio.

Vedi anche

• Panoramica dei plugin — come funzionano i plugin EmDash.
• Scegliere un formato di plugin — scrivi i tuoi widget di campo se Field Kit non si adatta.
• Discussione #571 — la proposta che ha portato a questo plugin.