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	Anzeigebezeichnung. Standardmäßig der Property-Schlüssel, verschönert — publishDate → “Publish Date”.
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",
    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
columnType	"varchar" | "text" | "char" | "uuid"	Datenbankspalte: "varchar" | "text" | "char" | "uuid"
isId	boolean | string	Primary key, and who fills it: "manual", "uuid", or any other string used verbatim as the column’s SQL default expression. The function has to exist; nothing here creates it. "increment" is a number strategy and does nothing here, and "cuid" is refused at config load
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. Unlike a string enum this creates no Postgres enum type — the column stays NUMERIC or INTEGER, so the panel offers the values and the database does not enforce them
columnType	string	"integer", "real", "double precision", "numeric", "bigint", "serial", "bigserial"
isId	boolean | string	Primary key: "manual", "increment", or any other string used verbatim as the column’s SQL default expression. "increment" is always INTEGER GENERATED BY DEFAULT AS IDENTITY — columnType beside it is ignored, with a warning
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	"timestamp" | "date" | "time"	"timestamp" | "date" | "time"
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"]
    }
}

In Postgres ist eine reference ein Fremdschlüssel wie jeder andere und folgt daher derselben ON DELETE-Regel wie eine belongsTo-Beziehung: optional ist SET NULL, erforderlich ist RESTRICT. Siehe Beziehungen.

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

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

Email and URL formats are not validation rules. email and url are flags on the property itself, beside type — statements about the data that the OpenAPI contract is generated from, rather than form behaviour:

properties: {
    email: { type: "string", name: "Email", email: true },
    website: { type: "string", name: "Website", url: true }
}

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