Eigenschaften

Überblick

Eigenschaften definieren die Spalten in Ihrer Datenbanktabelle und wie sie in der Admin-Benutzeroberfläche gerendert werden. Jede Eigenschaft hat einen type, der Folgendes bestimmt:

• Den Datenbankspaltentyp (über Drizzle-Schema-Generierung)
• Die Formularfeld-Komponente
• Den Tabellenzellen-Renderer
• Die Validierungs-Regeln

Eigenschaftstypen

Type	Beschreibung	PostgreSQL-Spalte
string	Text, Auswahl, Markdown, Dateiupload, URL, E-Mail	varchar, text, jsonb
number	Ganzzahl, Dezimalzahl, Währung	integer, numeric, bigint, serial
boolean	Wahr/Falsch-Umschalter	boolean
date	Datum, Datum/Uhrzeit, Zeitstempel	timestamp, date
array	Geordnete Liste von Werten	jsonb
map	Schlüssel-Wert-Objekt	jsonb
geopoint	Breiten-/Längengrad-Paar	jsonb
reference	Eingebetteter Verweis auf eine andere Entität	varchar (speichert ID)
relation	SQL-Fremdschlüsselbeziehung	Verwendet das relations-Array

Allgemeine Eigenschaften

Alle Eigenschaftstypen teilen diese Optionen:

Property	Type	Beschreibung
type	string	Erforderlich. Datentyp (siehe oben)
name	string	Erforderlich. Anzeigebezeichnung
description	string	Hilfetext, der unterhalb des Feldes angezeigt wird
defaultValue	any	Standardwert für neue Entitäten
validation	object	Validierungsregeln
propertyConfig	string	Registrierter Eigenschafts-Konfigurationsschlüssel
columnName	string	Expliziter Datenbankspaltenname (umgeht die snake_case-Konvertierung)
callbacks	PropertyCallbacks	Hooks für afterRead- und beforeSave-Transformationen
dynamicProps	function	Dynamischer Property-Builder (siehe Bedingte Felder)
conditions	PropertyConditions	Deklarative JSON Logic-Bedingungen

UI-Konfiguration (admin)

UI-bezogene Optionen werden im admin-Unterobjekt verschachtelt:

price: {
    type: "number",
    name: "Price",
    admin: {
        readOnly: true,
        columnWidth: 120,
        hideFromCollection: false
    }
}

Property	Type	Beschreibung
admin.readOnly	boolean	Bearbeitung verhindern
admin.disabled	boolean | PropertyDisabledConfig	Deaktivieren mit optionalem Tooltip
admin.hideFromCollection	boolean	Aus der Tabellenansicht ausblenden
admin.columnWidth	number	Spaltenbreite in Pixeln (Tabellenansicht)
admin.span	1 | 2 | 3 | 4	Feldbreite im vierspaltigen Formularraster
admin.Field	React.ComponentType	Benutzerdefinierte Feldkomponente
admin.Preview	React.ComponentType	Benutzerdefinierte Tabellenzellenkomponente

String-Eigenschaften

Der string-Typ ist am vielseitigsten — je nach den gesetzten Optionen wird er als unterschiedliche Widgets dargestellt.

Textfeld

Ein einfaches einzeiliges Texteingabefeld.

name: {
    type: "string",
    name: "Name",
    validation: { required: true, min: 2, max: 200 }
}

Mehrzeiliger Text

Setzen Sie multiline: true, um einen Textbereich darzustellen.

description: {
    type: "string",
    name: "Description",
    multiline: true
}

Markdown-Editor

Setzen Sie markdown: true, um einen vollständigen Markdown-Editor mit Werkzeugleiste darzustellen.

body: {
    type: "string",
    name: "Blog text",
    markdown: true
}

E-Mail-Feld

Setzen Sie email: true, um E-Mail-Formatvalidierung hinzuzufügen und mit einem E-Mail-Symbol darzustellen.

email: {
    type: "string",
    name: "User email",
    email: true,
    validation: { required: true }
}

URL-Feld

Setzen Sie url: true, um URL-Formatvalidierung hinzuzufügen und mit einem Link-Symbol darzustellen.

website: {
    type: "string",
    name: "Amazon link",
    url: true
}

Dateiupload

Setzen Sie storage, um eine Dateiupload-Dropzone darzustellen.

avatar: {
    type: "string",
    name: "Main image",
    storage: {
        storagePath: "avatars",
        acceptedFiles: ["image/*"],
        maxSize: 2 * 1024 * 1024
    }
}

Auswahl (Enum)

Setzen Sie enum, um eine Auswahl-Dropdown darzustellen. Siehe den Abschnitt Enum-Werte für Details.

category: {
    type: "string",
    name: "Category",
    enum: [
        { id: "electronics", label: "Electronics", color: "blueDark" },
        { id: "clothing", label: "Clothing", color: "pink" },
    ]
}

Mehrfachauswahl

Setzen Sie enum + multiSelect: true, um die Auswahl mehrerer Werte zu ermöglichen.

locales: {
    type: "string",
    name: "Available locales",
    multiSelect: true,
    enum: [
        { id: "es", label: "Spanish", color: "pink" },
        { id: "en", label: "English", color: "blueLight" },
        { id: "fr", label: "French", color: "purpleLight" },
    ]
}

String-Optionen

Property	Type	Beschreibung
admin.multiline	boolean	Als Textbereich rendern
admin.markdown	boolean	Als Markdown-Editor rendern
email	boolean	E-Mail-Formatvalidierung
url	boolean	URL-Formatvalidierung
storage	StorageConfig	Dateiupload aktivieren
enum	EnumValues	Als Auswahl-Dropdown rendern
multiSelect	boolean	Mehrere Enum-Auswahlen zulassen
columnType	string	Datenbankspalte: "varchar", "text"
isId	string	ID-Generierung: "uuid", "cuid", "increment", "manual"
userSelect	boolean	Als Benutzerauswahl rendern
admin.previewAsTag	boolean	Diese Zeichenkette als Tag in Vorschauen rendern
admin.clearable	boolean	Ein Symbol zum Löschen des Wertes hinzufügen (auf null setzen)

Zahlen-Eigenschaften

price: {
    type: "number",
    name: "Price",
    validation: { required: true, min: 0 }
}

quantity: {
    type: "number",
    name: "Quantity",
    columnType: "integer"  // Als Ganzzahl speichern
}

Zahlenfelder werden als Standard-Texteingabe mit numerischer Validierung dargestellt.

Zahlen-Optionen

Property	Type	Beschreibung
enum	EnumValues	Als Auswahl mit numerischen Werten rendern
columnType	string	"integer", "bigint", "numeric", "serial", "smallint"
isId	string	ID-Generierungsstrategie
admin.clearable	boolean	Ein Symbol zum Löschen des Wertes hinzufügen (auf null setzen)

Boolean-Eigenschaften

active: {
    type: "boolean",
    name: "Selectable",
    defaultValue: true
}

Boolean-Felder werden als Kippschalter dargestellt.

Datums-Eigenschaften

Nur Datum

Setzen Sie mode: "date", um einen Datumswähler ohne Uhrzeit anzuzeigen.

event_date: {
    type: "date",
    name: "Expiry date",
    mode: "date"
}

Datum und Uhrzeit

Der Standardmodus "date_time" enthält sowohl Datum als auch Uhrzeit.

arrival_time: {
    type: "date",
    name: "Arrival time",
    mode: "date_time"
}

Automatische Zeitstempel

Verwenden Sie autoValue, um Zeitstempel bei Erstellung oder Aktualisierung automatisch zu setzen.

createdAt: {
    type: "date",
    name: "Created At",
    autoValue: "on_create",
    admin: { readOnly: true }
}

updatedAt: {
    type: "date",
    name: "Updated At",
    autoValue: "on_update"
}

Datums-Optionen

Property	Type	Beschreibung
mode	"date" | "date_time"	Nur Datum oder Datum + Uhrzeit (Standard: "date_time")
autoValue	"on_create" | "on_update"	Zeitstempel automatisch setzen
columnType	string	"timestamp", "date"
timezone	string	Zeitzonen-String, um das Datum auszuwerten
admin.clearable	boolean	Ein Symbol zum Löschen des Wertes hinzufügen (auf null setzen)

Array-Eigenschaften

Einfache Wiederholung

Verwenden Sie of, um eine wiederholbare Liste von Elementen zu definieren.

tags: {
    type: "array",
    name: "Tags",
    of: { type: "string" }
}

Mehrfach-Dateiupload

Kombinieren Sie of mit storage für einen Mehrfach-Dateiupload.

images: {
    type: "array",
    name: "Images",
    of: {
        type: "string",
        storage: { storagePath: "images", acceptedFiles: ["image/*"] }
    }
}

Block-Editor

Verwenden Sie oneOf, um einen Block-Editor mit mehreren Inhaltstypen zu erstellen. Jeder Schlüssel erstellt einen Kartentyp, den Benutzer auswählen können.

content: {
    type: "array",
    name: "Content",
    oneOf: {
        properties: {
            text: {
                type: "map",
                properties: {
                    body: { type: "string", name: "Text", markdown: true }
                }
            },
            image: {
                type: "map",
                properties: {
                    src: { type: "string", name: "Image", storage: { storagePath: "content" } },
                    caption: { type: "string", name: "Caption" }
                }
            }
        }
    }
}

Array-Optionen

Property	Type	Beschreibung
of	Property | Property[]	Eigenschaftsschema für Array-Elemente
oneOf	object	Array von typisierten Objekten mit mehreren Diskriminator-Typen
admin.expanded	boolean	Soll das Feld anfänglich erweitert sein (Standard: true)
admin.minimalistView	boolean	Untergeordnete Eigenschaften direkt ohne erweiterbares Panel anzeigen
admin.sortable	boolean	Können Elemente neu angeordnet werden (Standard: true)
admin.canAddElements	boolean	Können neue Elemente hinzugefügt werden (Standard: true)

Map-Eigenschaften

Gruppe (strukturiert)

Verwenden Sie properties, um ein strukturiertes Objekt mit benannten Feldern zu definieren.

address: {
    type: "map",
    name: "Address",
    properties: {
        street: { type: "string", name: "Street" },
        zip: { type: "string", name: "Postal code" }
    }
}

Schlüssel-Wert (Freiform)

Setzen Sie keyValue: true, um einen Editor für beliebige Schlüssel-Wert-Paare darzustellen.

metadata: {
    type: "map",
    name: "Key value",
    keyValue: true
}

Map-Optionen

Property	Type	Beschreibung
properties	Properties	Datensatz der in der Map enthaltenen Eigenschaften
propertiesOrder	string[]	Geordnete Schlüssel für das Rendern
admin.previewProperties	string[]	Welche Eigenschaften in der Tabellenvorschau angezeigt werden sollen
admin.spreadChildren	boolean	Untergeordnete Eigenschaften als separate Spalten in der Tabellenansicht rendern
admin.minimalistView	boolean	Eigenschaften ohne umhüllendes Panel anzeigen
admin.expanded	boolean	Soll das Feld anfänglich erweitert sein (Standard: true)
keyValue	boolean	Als Editor für beliebige Schlüssel-Wert-Paare rendern

Referenz-Eigenschaften

Referenzen verlinken auf Entitäten in einer anderen Sammlung. Sie werden als Vorschaukarte dargestellt, die die Details der referenzierten Entität anzeigt.

client: {
    type: "reference",
    name: "Related client",
    path: "clients",
    admin: {
        previewProperties: ["first_name", "last_name", "email"]
    }
}

Referenz- und Relations-Optionen

Gelten sowohl für reference- als auch für relation-Eigenschaften.

Eigenschaft	Typ	Beschreibung
admin.fixedFilter	FilterValues	Filtert die im Auswahl-Widget angebotenen Einträge
admin.widget	"select" | "dialog"	Welches Widget die verknüpfte Entität auswählt (nur Relationen)
admin.includeId	boolean	Die Id der verknüpften Entität in Vorschauen anzeigen (Standard: true)
admin.includeEntityLink	boolean	Einen Link zum Öffnen der verknüpften Entität anzeigen (Standard: true)
admin.previewProperties	string[]	Welche Eigenschaften des Ziels in der Vorschau erscheinen (max. 3)

Enum-Werte

Wird mit String- oder Zahlen-Eigenschaften verwendet, um Auswahlen zu rendern:

// Einfaches Array
enum: ["draft", "published", "archived"]

// Mit Bezeichnungen
enum: [
    { id: "draft", label: "Draft" },
    { id: "published", label: "Published" },
    { id: "archived", label: "Archived" }
]

// Mit Farben (für Kanban-Spalten und Chips)
enum: [
    { id: "draft", label: "Draft", color: "grayDark" },
    { id: "published", label: "Published", color: "greenDark" },
    { id: "archived", label: "Archived", color: "orangeDark" }
]

Validierung

validation: {
    required: true,             // Feld ist erforderlich
    unique: true,               // Muss in der Tabelle eindeutig sein
    requiredMessage: "Custom error message",

    // Zeichenketten-spezifisch
    min: 2,                     // Minimale Länge
    max: 200,                   // Maximale Länge
    matches: /^[a-z]+$/,       // Regex-Muster
    email: true,                // E-Mail-Format
    url: true,                  // URL-Format

    // Zahlen-spezifisch
    min: 0,                     // Minimaler Wert
    max: 1000,                  // Maximaler Wert
    integer: true,              // Muss eine Ganzzahl sein

    // Array-spezifisch
    min: 1,                     // Minimale Anzahl von Elementen
    max: 10,                    // Maximale Anzahl von Elementen
}

Bedingte Felder

Sie können Felder dynamisch gestalten, sodass sie auf die Werte der Entität reagieren. Dafür gibt es zwei Möglichkeiten:

1. JSON Logic Bedingungen (Deklarativ)

Sie können die Eigenschaft conditions verwenden, um deklarative JSON Logic-Regeln zu definieren, die im Sammlungseditor serialisiert und visuell geändert werden können.

price: {
    type: "number",
    name: "Price",
    conditions: {
        disabled: { "==": [{ "var": "values.is_free" }, true] },
        required: { "!=": [{ "var": "values.is_free" }, true] },
        min: 0,
        clearOnDisabled: true // Auf null setzen, wenn das Feld deaktiviert wird
    }
}

Das conditions-Objekt bietet Ihnen Zugriff auf:

• disabled, hidden, readOnly
• required, min, max
• defaultValue
• enumConditions, allowedEnumValues, excludedEnumValues
• referencePath, referenceFilter
• canAddElements, sortable (für Arrays)

2. Property Builders (Programmatisch)

Für komplexes Verhalten, das nicht über JSON Logic ausgedrückt werden kann, können Sie dynamicProps verwenden, das eine Javascript-Funktion auswertet.

price: {
    type: "number",
    name: "Price",
    dynamicProps: ({ values, user }) => ({
        disabled: values.is_free === true || !user.roles.includes("admin"),
        validation: values.is_free ? {} : { required: true, min: 0 }
    })
}

Nächste Schritte

• Beziehungen — Fremdschlüssel und Joins
• Sicherheitsregeln — Zeilenebenen-Sicherheit
• Benutzerdefinierte Felder — Benutzerdefinierte Feldkomponenten erstellen