Vue 3 Formulararchitektur für Business-Apps: wiederverwendbare Muster

Warum Formular-Code in echten Business-Apps auseinanderfällt

Ein Formular in einer Business-App bleibt selten klein. Es beginnt als „nur ein paar Eingaben“ und wächst dann zu dutzenden Feldern, bedingten Abschnitten, Berechtigungen und Regeln, die mit der Backend-Logik in Einklang bleiben müssen. Nach ein paar Produktänderungen funktioniert das Formular noch, aber der Code fühlt sich fragil an.

Die Formulararchitektur in Vue 3 ist wichtig, weil Formulare Orte sind, an denen sich „schnelle Korrekturen“ stapeln: noch ein Watcher, noch ein Spezialfall, noch eine kopierte Komponente. Heute funktioniert es, aber es wird schwerer, dem zu vertrauen und Änderungen vorzunehmen.

Die Warnzeichen sind vertraut: Eingabeverhalten, das sich über Seiten wiederholt (Label, Formatierung, Pflicht-Markierungen, Hinweise), inkonsistente Fehlerplatzierung, Validierungsregeln, die über Komponenten verstreut sind, und Backend-Fehler, die auf eine generische Toast-Nachricht reduziert werden, die den Nutzer nicht sagt, was er beheben muss.

Diese Inkonsistenzen sind nicht nur Stilfragen im Code. Sie werden zu UX-Problemen: Leute schicken Formulare erneut ab, Support-Tickets steigen und Teams trauen sich nicht, Formulare anzufassen, weil irgendwo ein versteckter Randfall brechen könnte.

Eine gute Einrichtung macht Formulare auf die beste Art langweilig. Mit einer vorhersehbaren Struktur kannst du Felder hinzufügen, Regeln ändern und Serverantworten behandeln, ohne alles umzustellen.

Du willst ein Formsystem, das Wiederverwendbarkeit bietet (ein Feld verhält sich überall gleich), Klarheit (Regeln und Fehlerbehandlung sind leicht zu überblicken), vorhersehbares Verhalten (touched, dirty, reset, submit) und besseres Feedback (Server-Fehler erscheinen bei genau den Eingaben, die Aufmerksamkeit benötigen). Die folgenden Muster konzentrieren sich auf wiederverwendbare Feldkomponenten, lesbare Validierung und das Zurückführen von Serverfehlern auf konkrete Inputs.

Ein einfaches Gedankenmodell für Formularstruktur

Ein Formular, das über die Zeit hält, ist ein kleines System mit klaren Teilen, nicht ein Haufen Eingaben.

Denk an vier Schichten, die in eine Richtung miteinander kommunizieren: die UI sammelt Eingaben, der Formularzustand speichert sie, die Validierung erklärt, was falsch ist, und die API-Schicht lädt und speichert.

Die vier Schichten (und was jede besitzt)

• Field UI component: rendert das Input, Label, Hint und Fehlermeldung. Emitiert Werteänderungen.
• Form state: hält Werte und Fehler (plus touched- und dirty-Flags).
• Validation rules: pure Funktionen, die Werte lesen und Fehlermeldungen zurückgeben.
• API calls: laden Initialdaten, senden Änderungen und übersetzen Serverantworten in Feldfehler.

Diese Trennung hält Änderungen eingegrenzt. Wenn eine neue Anforderung kommt, aktualisierst du eine Schicht, ohne die anderen kaputt zu machen.

Was gehört in ein Feld vs. ins übergeordnete Formular

Eine wiederverwendbare Feldkomponente sollte langweilig sein. Sie sollte nichts über deine API, dein Datenmodell oder deine Validierungsregeln wissen. Sie sollte nur einen Wert anzeigen und einen Fehler zeigen.

Das übergeordnete Formular koordiniert alles andere: welche Felder existieren, wo Werte liegen, wann validiert wird und wie abgeschickt wird.

Eine einfache Regel hilft: Wenn Logik von anderen Feldern abhängt (zum Beispiel: „State ist nur dann erforderlich, wenn Country US ist“), behalte sie im übergeordneten Formular oder in der Validierungsschicht, nicht in der Feldkomponente.

Wenn das Hinzufügen eines neuen Feldes wirklich wenig Aufwand ist, änderst du normalerweise nur die Defaults oder das Schema, das Markup, wo das Feld platziert ist, und die Validierungsregeln des Feldes. Wenn das Hinzufügen eines Eingabefeldes Änderungen über nicht verwandte Komponenten hinweg erzwingt, sind deine Grenzen verschwommen.

Wiederverwendbare Feldkomponenten: Was zu standardisieren ist

Wenn Formulare wachsen, ist der schnellste Gewinn aufzuhören, jedes Input wie ein Einzelfall zu bauen. Feldkomponenten sollten vorhersehbar sein. Das macht sie schnell zu verwenden und leicht zu überprüfen.

Praktische Bausteine:

• BaseField: Wrapper für Label, Hint, Fehlermeldung, Abstände und Accessibility-Attribute.
• Input-Komponenten: TextInput, SelectInput, DateInput, Checkbox usw. Jede konzentriert sich auf das Steuerelement.
• FormSection: gruppiert verwandte Felder mit Titel, kurzem Hilfetext und konsistenten Abständen.

Bei Props halte die Menge klein und setze sie überall durch. Einen Prop-Namen in 40 Formularen zu ändern ist schmerzhaft.

Diese zahlen sich üblicherweise sofort aus:

• modelValue und update:modelValue für v-model
• label
• required
• disabled
• error (einzelne Nachricht oder ein Array, je nach Vorliebe)
• hint

Slots erlauben Flexibilität, ohne Konsistenz zu brechen. Behalte das Layout von BaseField stabil, aber erlaube kleine Variationen wie eine Aktion rechts ("Code senden") oder ein führendes Icon. Wenn eine Variation zweimal auftaucht, mach daraus einen Slot statt die Komponente zu forken.

Standardisiere die Render-Reihenfolge (Label, Control, Hint, Error). Nutzer scannen schneller, Tests werden einfacher und die Zuordnung von Server-Fehlern wird unkompliziert, weil jedes Feld einen offensichtlichen Platz hat, um Nachrichten anzuzeigen.

Formularzustand: values, touched, dirty und reset

Die meisten Formularfehler in Business-Apps drehen sich nicht um Inputs. Sie kommen von verstreutem Zustand: Werte an einem Ort, Fehler an einem anderen und ein Reset-Button, der nur halb funktioniert. Eine saubere Vue-3-Formulararchitektur beginnt mit einer konsistenten State-Form.

Zuerst: Wähle eine Namenskonvention für Feldschlüssel und halte dich daran. Die einfachste Regel ist: der Feldschlüssel entspricht dem API-Payload-Schlüssel. Wenn dein Server first_name erwartet, sollte dein Formularschlüssel ebenfalls first_name heißen. Diese kleine Wahl macht Validierung, Speichern und Zuordnung von Serverfehlern viel einfacher.

Halte deinen Formularzustand an einem Ort (ein Composable, ein Pinia-Store oder eine Parent-Komponente) und lass jedes Feld durch diesen Zustand lesen und schreiben. Eine flache Struktur funktioniert für die meisten Screens. Gehe nur dann verschachtelt, wenn deine API wirklich verschachtelt ist.

const state = reactive({
  values: { first_name: '', last_name: '', email: '' },
  touched: { first_name: false, last_name: false, email: false },
  dirty: { first_name: false, last_name: false, email: false },
  errors: { first_name: '', last_name: '', email: '' },
  defaults: { first_name: '', last_name: '', email: '' }
})

Eine praktische Denkweise für die Flags:

• touched: Hat der Nutzer mit diesem Feld interagiert?
• dirty: Ist der Wert anders als der Default- (oder zuletzt gespeicherte) Wert?
• errors: Welche Nachricht sollte der Nutzer gerade sehen?
• defaults: Worauf setzen wir beim Reset zurück?

Das Reset-Verhalten sollte vorhersehbar sein. Wenn du einen bestehenden Datensatz lädst, setze sowohl values als auch defaults aus derselben Quelle. Dann kann reset() defaults zurück in values kopieren, touched löschen, dirty löschen und errors löschen.

Beispiel: Ein Kundenprofil-Formular lädt email vom Server. Wenn der Nutzer es bearbeitet, wird dirty.email true. Klickt er auf Reset, geht die Email zurück zum geladenen Wert (nicht zu einem leeren String), und der Bildschirm sieht wieder sauber aus.

Validierungsregeln, die lesbar bleiben

Lesbare Validierung ist weniger eine Frage der Bibliothek als wie du Regeln ausdrückst. Wenn du bei einem Blick auf ein Feld seine Regeln in wenigen Sekunden verstehst, bleibt dein Formularcode wartbar.

Wähle einen Regelstil, bei dem ihr bleibt

Die meisten Teams wählen eine dieser Herangehensweisen:

• Pro-Feld-Regeln: Regeln leben nahe der Feldnutzung. Leicht zu überblicken, gut für kleine bis mittlere Formulare.
• Schema-basierte Regeln: Regeln leben in einem Objekt oder einer Datei. Gut, wenn viele Screens dasselbe Modell wiederverwenden.
• Hybrid: Einfache Regeln nahe bei den Feldern, geteilte oder komplexe Regeln in einem zentralen Schema.

Egal was du wählst: Halte Regelnamen und Nachrichten vorhersehbar. Ein paar gemeinsame Regeln (required, length, format, range) sind besser als eine lange Liste von Einzelhelfern.

Schreibe Regeln wie klares Englisch

Eine gute Regel liest sich wie ein Satz: „Email ist erforderlich und muss wie eine Email aussehen.“ Vermeide clevere Einzeiler, die die Absicht verstecken.

Für die meisten Business-Formulare ist es hilfreich, pro Feld jeweils eine Nachricht zurückzugeben (die erste fehlgeschlagene Regel). Das hält die UI ruhig und hilft Nutzern, schneller zu korrigieren.

Gängige Regeln, die nutzerfreundlich bleiben:

• Required nur wenn der Nutzer das Feld wirklich ausfüllen muss.
• Length mit echten Zahlen (z. B. 2 bis 50 Zeichen).
• Format für Email, Telefon, PLZ, ohne übermäßig strikte Regex, die echte Eingaben ablehnen.
• Range wie „Datum nicht in der Zukunft“ oder „Menge zwischen 1 und 999."

Mache asynchrone Prüfungen sichtbar

Asynchrone Validierung (z. B. „Benutzername bereits vergeben“) wird verwirrend, wenn sie still abläuft.

Starte Prüfungen bei Blur oder nach kurzer Pause, zeige einen klaren „Prüfe…“-Zustand und breche veraltete Requests ab oder ignoriere sie, wenn der Nutzer weiter tippt.

Entscheide, wann validiert wird

Timing ist genauso wichtig wie Regeln. Eine nutzerfreundliche Einrichtung ist:

• On change für Felder, die von Live-Feedback profitieren (z. B. Passwortstärke), aber behutsam.
• On blur für die meisten Felder, damit Nutzer tippen können ohne ständige Fehler.
• On submit für das gesamte Formular als letzte Sicherheitsstufe.

Serverfehler an das richtige Input zurückgeben

Client-seitige Prüfungen sind nur die halbe Geschichte. In Business-Apps lehnt der Server Saves wegen Regeln ab, die der Browser nicht kennt: Duplikate, Berechtigungsprüfungen, veraltete Daten, Zustandsänderungen und mehr. Gute Form-UX hängt davon ab, diese Antwort in klare Nachrichten neben den richtigen Inputs zu verwandeln.

Normalisiere Fehler in eine interne Form

Backends stimmen selten im Fehlerformat überein. Manche geben ein einzelnes Objekt zurück, andere Listen, wieder andere verschachtelte Maps, die nach Feldname geordnet sind. Konvertiere alles, was du bekommst, in eine interne Form, die dein Formular rendern kann.

// what your form code consumes
{
  fieldErrors: { "email": ["Already taken"], "address.street": ["Required"] },
  formErrors: ["You do not have permission to edit this customer"]
}

Halte ein paar Regeln konsistent:

• Speichere Feldfehler als Arrays (auch wenn nur eine Nachricht vorhanden ist).
• Konvertiere verschiedene Pfadstile in einen Stil (Punktnotation funktioniert gut: address.street).
• Bewahre Nicht-Feld-Fehler separat als formErrors.
• Bewahre die rohe Server-Payload zum Logging, rendere sie aber nicht.

Mappe Server-Pfade auf deine Feldschlüssel

Das Schwierige ist, die Server-Vorstellung eines „Pfads“ mit den Feldschlüsseln deines Formulars in Einklang zu bringen. Entscheide den Schlüssel für jede Feldkomponente (z. B. email, profile.phone, contacts.0.type) und halte dich daran.

Schreibe dann einen kleinen Mapper, der die gängigen Fälle behandelt:

• address.street (Punkt-Notation)
• address[0].street (Klammern für Arrays)
• /address/street (JSON-Pointer-Stil)

Nach der Normalisierung sollte \u003cField name="address.street" /\u003e fieldErrors["address.street"] ohne Spezialfälle lesen können.

Unterstütze Aliase, wenn nötig. Wenn das Backend customer_email zurückgibt, dein UI aber email verwendet, behalte während der Normalisierung eine Abbildung wie { customer_email: "email" } bei.

Feldfehler, Formularfehler und Fokussieren

Nicht jeder Fehler gehört zu einem einzelnen Input. Wenn der Server „Plan-Limit erreicht“ oder „Zahlung erforderlich“ meldet, zeige das oberhalb des Formulars als Formular-Fehlermeldung.

Bei feldspezifischen Fehlern: zeige die Nachricht neben dem Input und leite den Nutzer zum ersten Problem:

• Nachdem du Serverfehler gesetzt hast, finde den ersten Schlüssel in fieldErrors, der in deinem gerenderten Formular vorhanden ist.
• Scrolle zu diesem Feld und fokussiere es (mittels Ref pro Feld und nextTick).
• Lösche Serverfehler für ein Feld, wenn der Nutzer dieses Feld erneut bearbeitet.

Schritt für Schritt: Architektur zusammenfügen

Formulare bleiben ruhig, wenn du früh entscheidest, was zum Formularzustand, zur UI, zu Validierung und zur API gehört, und diese mit ein paar kleinen Funktionen verbindest.

Eine Sequenz, die für die meisten Business-Apps funktioniert:

• Starte mit einem Formularmodell und stabilen Feldschlüsseln. Diese Schlüssel werden zum Vertrag zwischen Komponenten, Validatoren und Serverfehlern.
• Erstelle einen BaseField-Wrapper für Label, Hilfetext, Pflicht-Markierung und Fehleranzeige. Halte Input-Komponenten klein und konsistent.
• Füge eine Validierungsebene hinzu, die pro Feld laufen kann und alles beim Submit validiert.
• Sende an die API. Wenn es fehlschlägt, übersetze Serverfehler in { [fieldKey]: message }, sodass das richtige Input die richtige Nachricht anzeigt.
• Halte die Erfolgshandhabung getrennt (reset, Toast, Navigation), damit sie nicht in Komponenten oder Validatoren hineinleakt.

Ein einfacher Ausgangspunkt für State:

const values = reactive({ email: '', name: '', phone: '' })
const touched = reactive({ email: false, name: false, phone: false })
const errors = reactive({}) // { email: '...', name: '...' }

Dein BaseField erhält label, error und vielleicht touched und rendert die Nachricht an einer Stelle. Jede Input-Komponente kümmert sich nur ums Binden und Emittieren von Updates.

Für die Validierung: behalte Regeln in der Nähe des Modells mit denselben Schlüsseln:

const rules = {
  email: v => (!v ? 'Email is required' : /@/.test(v) ? '' : 'Enter a valid email'),
  name: v => (v.length < 2 ? 'Name is too short' : ''),
}

function validateAll() {
  Object.keys(rules).forEach(k => {
    const msg = rules[k](values[k])
    if (msg) errors[k] = msg
    else delete errors[k]
    touched[k] = true
  })
  return Object.keys(errors).length === 0
}

Wenn der Server mit Fehlern antwortet, mappe sie mit denselben Schlüsseln. Wenn die API { "field": "email", "message": "Already taken" } zurückgibt, setze errors.email = 'Already taken' und markiere es als touched. Ist der Fehler global (z. B. "permission denied"), zeige ihn oberhalb des Formulars an.

Beispiel-Szenario: Kundenprofil bearbeiten

Stell dir einen internen Admin-Screen vor, in dem ein Support-Agent ein Kundenprofil bearbeitet. Das Formular hat vier Felder: name, email, phone und role (Customer, Manager, Admin). Es ist klein, zeigt aber die üblichen Probleme.

Client-seitige Regeln sollten klar sein:

• Name: erforderlich, Mindestlänge.
• Email: erforderlich, gültiges Email-Format.
• Phone: optional, aber wenn ausgefüllt, muss es deinem akzeptierten Format entsprechen.
• Role: erforderlich, und manchmal konditional (nur Nutzer mit bestimmten Berechtigungen können Admin zuweisen).

Ein konsistenter Komponentenvertrag hilft: jedes Feld erhält den aktuellen Wert, den aktuellen Fehltext (falls vorhanden) und ein paar Booleans wie touched und disabled. Labels, Pflicht-Markierungen, Abstände und Fehler-Styling sollten nicht auf jedem Screen neu erfunden werden.

Jetzt der UX-Fluss. Der Agent ändert die Email, tabbt heraus und sieht eine Inline-Meldung unter Email, wenn das Format falsch ist. Er korrigiert es, klickt Speichern und der Server antwortet:

• email already exists: Zeige es unter Email und fokussiere dieses Feld.
• phone invalid: Zeige es unter Phone.
• permission denied: Zeige eine formularweite Nachricht oben.

Wenn du Fehler nach Feldname (email, phone, role) schlüsselst, ist das Mapping einfach. Feldfehler landen neben Inputs, Formularfehler in einem dedizierten Bereich.

Häufige Fehler und wie man sie vermeidet

Logik an einem Ort halten

Validierungsregeln in jedem Screen zu kopieren fühlt sich schnell an, bis sich Policies ändern (Passwortregeln, Pflicht-Steuer-IDs, erlaubte Domains). Halte Regeln zentralisiert (Schema, Rules-File, geteilte Funktionen) und lass Formulare dasselbe Regelset konsumieren.

Vermeide außerdem, dass Low-Level-Inputs zu viel tun. Wenn dein <TextField> die API aufruft, auf Fehler erneut versucht und Server-Error-Payloads parst, ist es nicht mehr wiederverwendbar. Feldkomponenten sollen rendern, Werte-Updates emittieren und Fehler anzeigen. API-Aufrufe und Mapping-Logik gehören in den Formular-Container oder ein Composable.

Symptome, dass du Zuständigkeiten mischst:

• Dieselbe Validierungsnachricht steht an mehreren Stellen.
• Eine Feldkomponente importiert einen API-Client.
• Das Ändern eines Endpunkts bricht mehrere nicht zusammenhängende Formulare.
• Tests müssen die halbe App mounten, nur um ein Input zu prüfen.

UX- und Accessibility-Fallen

Ein einzelnes Fehler-Banner wie „Etwas ist schiefgelaufen“ reicht nicht aus. Nutzer müssen wissen, welches Feld falsch ist und was zu tun ist. Nutze Banner für globale Fehler (Netzwerk down, permission denied) und mappe Serverfehler zu spezifischen Inputs, damit Nutzer sie schnell beheben können.

Loading- und Double-Submit-Probleme erzeugen verwirrende Zustände. Beim Absenden: Disable Submit, disable Felder, die sich während des Speicherns nicht ändern sollten, und zeige einen klaren Busy-State. Sorge dafür, dass Reset und Cancel das Formular sauber zurücksetzen.

Accessibility-Grundlagen werden bei Custom-Komponenten leicht übersehen. Ein paar Entscheidungen verhindern echten Ärger:

• Jedes Input hat ein sichtbares Label (nicht nur Placeholder).
• Fehler sind mit den Feldern mittels geeigneter aria-Attribute verbunden.
• Der Fokus springt nach Submit zum ersten ungültigen Feld.
• Deaktivierte Felder sind wirklich nicht interaktiv und werden korrekt angekündigt.
• Tastatur-Navigation funktioniert durchgehend.

Schnelle Checkliste und nächste Schritte

Bevor du ein neues Formular auslieferst, lauf eine kurze Checkliste durch. Sie fängt die kleinen Lücken ein, die später Support-Tickets verursachen.

• Hat jedes Feld einen stabilen Schlüssel, der Payload und Serverantworten entspricht (inklusive verschachtelter Pfade wie billing.address.zip)?
• Kannst du jedes Feld mit einer konsistenten Field-Component-API rendern (Wert rein, Events raus, Error und Hint rein)?
• Validierst du beim Submit einmal, blockierst doppelte Submits und fokussierst das erste ungültige Feld, damit Nutzer wissen, wo sie anfangen sollen?
• Zeigst du Fehler am richtigen Ort: pro Feld (neben dem Input) und auf Formular-Ebene (allgemeine Nachricht wenn nötig)?
• Setzt du nach Erfolg den State korrekt zurück (values, touched, dirty), sodass die nächste Bearbeitung sauber beginnt?

Wenn eine Antwort „nein“ ist, behebe das zuerst. Der häufigste Schmerzpunkt ist Drift: Feldnamen weichen von der API ab oder Serverfehler kommen in einer Form zurück, die deine UI nicht zuordnen kann.

Wenn du interne Tools baust und schneller werden willst, folgt AppMaster (appmaster.io) denselben Grundlagen: Field-UI konsistent halten, Regeln und Workflows zentralisieren und Serverantworten dort anzeigen, wo Nutzer handeln können.