Benutzerdefinierte Vue‑Komponenten in generierter UI — sicher mit Regeneration

Was kaputtgeht, wenn Sie eine generierte UI bearbeiten

Generierte UIs sind zum Wiederaufbau gedacht. In Plattformen wie AppMaster wird Vue3‑Web‑App‑Code aus visuellen Editoren erzeugt. Regeneration sorgt dafür, dass Änderungen über Bildschirme, Logik und Datenmodelle hinweg konsistent bleiben.

Der Haken ist einfach: Wenn Sie generierte Dateien direkt bearbeiten, kann die nächste Regeneration Ihre Änderungen überschreiben.

Deshalb greifen Teams zu benutzerlichem Code. Die eingebauten UI‑Bausteine decken oft Standardformulare und Tabellen ab, aber echte Apps brauchen normalerweise ein paar spezielle Teile: komplexe Diagramme, Karten‑Picker, Rich‑Text‑Editoren, Unterschriftsfelder oder Drag‑and‑Drop‑Planer. Das sind gute Gründe, benutzerdefinierte Vue‑Komponenten hinzuzufügen — vorausgesetzt, Sie behandeln sie als Erweiterungen, nicht als direkte Änderungen.

Wenn sich Custom‑Code und generierter Code vermischen, treten Fehler oft spät und verwirrend auf. Sie bemerken das möglicherweise erst, wenn eine weitere UI‑Änderung eine Regeneration auslöst oder ein Kollege einen Screen im visuellen Editor anpasst. Häufige Probleme sind:

• Ihr benutzerliches Markup verschwindet, weil das Template neu erzeugt wurde.
• Imports oder Registrierungen brechen, weil sich Dateinamen oder Strukturen geändert haben.
• Ein „kleiner Fix“ wird bei jedem Deploy zum Merge‑Konflikt.
• Generierte Logik und benutzerliche Logik driftet auseinander, sodass Randfälle anfangen zu scheitern.
• Upgrades fühlen sich riskant an, weil Sie nicht wissen, was ersetzt wird.

Das Ziel ist nicht, Anpassungen zu verbieten. Es geht darum, Wiederaufbauten vorhersehbar zu machen. Wenn Sie eine saubere Grenze zwischen generierten Screens und benutzerlichen Widgets halten, bleibt Regeneration Routine statt Stress.

Eine Grenzregel, die Regeneration sicher macht

Wenn Sie anpassen wollen, ohne Arbeit zu verlieren: Folgen Sie einer Regel: Bearbeiten Sie niemals generierte Dateien. Behandeln Sie sie als read‑only Output, wie ein kompiliertes Artefakt.

Denken Sie an Ihre UI als zwei Zonen:

• Generated zone: Seiten, Layouts und Screens, die der Generator erzeugt.
• Custom zone: Ihre handgeschriebenen Vue‑Komponenten in einem eigenen Ordner.

Die generierte UI sollte Ihre benutzerlichen Komponenten konsumieren. Sie sollte nicht der Ort sein, an dem diese Komponenten gebaut werden.

Damit das langfristig funktioniert, halten Sie die „Grenze“ klein und klar. Ein Custom‑Widget sollte sich wie ein kleines Produkt mit Vertrag verhalten:

• Props rein: nur das, was es zum Rendern braucht.
• Events raus: nur das, worauf die Seite reagieren muss.

Vermeiden Sie es, aus dem Widget heraus globalen State zu durchdringen oder unzusammenhängende APIs aufzurufen, es sei denn, das gehört ausdrücklich zum Vertrag.

Bei AppMaster‑ähnlichen generierten Vue3‑Screens bedeutet das typischerweise: Sie machen nur minimale Verkabelung in der generierten Seite, um Props zu übergeben und Events zu behandeln. Diese Verkabelung kann sich bei Regeneration ändern, bleibt aber klein und leicht wiederherstellbar. Die eigentliche Arbeit bleibt sicher in der Custom‑Zone.

Isolationsmuster, die mit Vue3 gut funktionieren

Das Ziel ist klar: Regeneration sollte generierte Dateien frei ersetzen können, während Ihr Widget‑Code unberührt bleibt.

Ein praktikabler Ansatz ist, maßgeschneiderte Widgets als kleines internes Modul zu halten: Komponenten, Styles und Hilfs‑Utilities an einem Ort. In generierten Vue3‑Apps bedeutet das meist, dass Custom‑Code außerhalb der generierten Seiten liegt und als Abhängigkeit importiert wird.

Ein Wrapper‑Component hilft sehr. Lassen Sie den Wrapper mit der generierten App sprechen: lesen Sie die vorhandene Datenform der Seite, normalisieren Sie sie und geben Sie saubere Props an das Widget weiter. Ändert sich die generierte Datenform später, aktualisieren Sie häufig nur den Wrapper statt das Widget.

Einige Muster, die sich bewähren:

• Behandeln Sie das Widget als Black‑Box: Props rein, Events raus.
• Nutzen Sie einen Wrapper, um API‑Antworten, Datumsformate und IDs in widget‑freundliche Formate zu überführen.
• Halten Sie Styles scoped, damit regenerierte Seiten Ihr Widget nicht versehentlich überschreiben.
• Verlassen Sie sich nicht auf die Eltern‑DOM‑Struktur oder seiten‑spezifische Klassennamen.

Beim Styling: Bevorzugen Sie scoped CSS (oder CSS Modules) und namespace geteilte Klassen. Wenn das Widget das App‑Theme anpassen soll, übergeben Sie Theme‑Tokens als Props (Farben, Abstände, Schriftgröße) statt Seitenstyles zu importieren.

Slots sind sicher, wenn sie klein und optional bleiben, etwa eine „Empty State“‑Nachricht. Wenn Slots anfangen, das Kerndesign oder Verhalten zu steuern, haben Sie das Widget wieder in die generierte Schicht gezogen — und damit beginnt der Regenerations‑Schmerz.

Entwurf eines stabilen Komponentenvertrags (Props und Events)

Der sicherste Weg, Regeneration schmerzfrei zu halten, ist jedes Widget wie ein stabiles Interface zu behandeln. Generierte Screens können sich ändern. Ihre Komponente nicht.

Beginnen Sie mit Eingaben (Props). Halten Sie sie wenige, vorhersagbar und einfach zu validieren. Bevorzugen Sie primitive Typen und plain objects, die Sie kontrollieren. Fügen Sie Defaults hinzu, damit das Widget auch dann sinnvoll reagiert, wenn eine Seite noch nichts übergibt. Wenn etwas fehlerhaft sein kann (IDs, Datumsstrings, Enum‑ähnliche Werte), validieren Sie und versagen Sie weich: zeigen Sie einen Empty State an, statt abzustürzen.

Für Ausgaben standardisieren Sie Events, damit Widgets konsistent wirken. Ein verlässliches Set ist:

• update:modelValue für v-model
• change für vom Nutzer bestätigte Änderungen (nicht jeden Tastschlag)
• error, wenn das Widget seine Aufgabe nicht erfüllen kann
• ready, wenn asynchrone Arbeit abgeschlossen ist und das Widget nutzbar ist

Wenn asynchrone Arbeit beteiligt ist, machen Sie das Teil des Vertrags. Bieten Sie loading und disabled Props an und überlegen Sie errorMessage für serverseitige Fehler. Wenn die Komponente selbst Daten lädt, emittieren Sie trotzdem error und ready, damit der Parent reagieren kann (Toast, Logging, Fallback‑UI).

Erwartungen an Barrierefreiheit

Bauen Sie Accessibility in den Vertrag ein. Akzeptieren Sie eine label‑ oder ariaLabel‑Prop, dokumentieren Sie Tastaturverhalten und halten Sie Fokus‑Verhalten vorhersehbar nach Aktionen.

Ein Beispiel: Ein Timeline‑Widget auf einem Dashboard sollte Pfeiltasten unterstützen, um zwischen Einträgen zu wechseln, Enter zum Öffnen von Details und den Fokus zurückgeben an die Steuerung, die ein Dialog geöffnet hat, wenn dieser schließt. So bleibt das Widget auf verschiedenen regenerierten Screens wiederverwendbar, ohne zusätzlichen Aufwand.

Schritt für Schritt: Ein maßgeschneidertes Widget hinzufügen, ohne generierte Dateien zu berühren

Fangen Sie klein an: ein Screen, den Nutzer wirklich brauchen, ein Widget, das ihn unterscheidbar macht. Eine enge erste Änderung macht es leichter zu sehen, was die Regeneration beeinflusst.

1. Erstellen Sie die Komponente außerhalb des generierten Bereichs. Legen Sie sie in einen Ordner, den Sie besitzen und unter Versionskontrolle halten (häufig custom oder extensions).

2. Halten Sie die öffentliche Oberfläche klein. Ein paar Props rein, ein paar Events raus. Geben Sie nicht den ganzen Seiten‑State weiter.

3. Fügen Sie einen dünnen Wrapper hinzu, den Sie ebenfalls besitzen. Seine Aufgabe ist, generierte Seitendaten in den Widget‑Vertrag zu übersetzen.

4. Integrieren Sie über einen unterstützten Extension‑Punkt. Referenzieren Sie den Wrapper so, dass Sie die generierten Dateien nicht bearbeiten müssen.

5. Regenerieren und verifizieren. Ihr Custom‑Ordner, Wrapper und Component sollten unverändert bleiben und weiterhin kompilieren.

Halten Sie Grenzen scharf. Das Widget konzentriert sich auf Darstellung und Interaktion. Der Wrapper mappt Daten und leitet Aktionen weiter. Geschäftsregeln bleiben in der Logikschicht (Backend oder gemeinsamen Prozessen), nicht im Widget vergraben.

Ein sinnvoller Schnelltest: Wenn jetzt regeneriert würde, könnte ein Kollege die App neu bauen und das gleiche Ergebnis erzielen, ohne manuelle Änderungen neu vorzunehmen? Wenn ja, ist das Muster solide.

Wo Logik hingehört, damit die UI wartbar bleibt

Ein Custom‑Widget sollte sich hauptsächlich darum kümmern, wie es aussieht und wie es auf Eingaben reagiert. Je mehr Geschäftsregeln Sie ins Widget packen, desto schwerer lässt es sich wiederverwenden, testen und ändern.

Eine gute Faustregel: Geschäftslogik in der Page‑ oder Feature‑Schicht, das Widget „dumm“ halten. Die Seite entscheidet, welche Daten das Widget bekommt und was passiert, wenn das Widget ein Event emittiert. Das Widget rendert und meldet Benutzerintentionen.

Wenn Sie Logik nahe am Widget brauchen (Formatierung, kleiner State, client‑seitige Validierung), kapseln Sie sie hinter einer kleinen Service‑Schicht. In Vue3 kann das ein Modul, ein Composable oder ein Store mit klarer API sein. Das Widget importiert diese API, nicht zufällige App‑Interna.

Eine praktische Aufteilung:

• Widget (Komponente): UI‑State, Input‑Handling, Visuals, emittiert Events wie select, change, retry.
• Service/Composable: Datenformung, Caching, Mapping von API‑Fehlern auf nutzerfreundliche Meldungen.
• Page/Container: Geschäftsregeln, Berechtigungen, welche Daten geladen werden, wann gespeichert wird.
• Generierte App‑Teile: unberührt lassen; Daten über Props geben und Events hören.

Vermeiden Sie direkte API‑Aufrufe im Widget, außer das gehört explizit zum Vertrag des Widgets. Wenn es das Laden übernimmt, machen Sie das offensichtlich (zum Beispiel CustomerSearchWidget) und halten Sie die Aufruflogik an einer Stelle.

Fehlermeldungen sollten nutzerfreundlich und konsistent sein. Statt rohen Servertext zu zeigen, mappen Sie Fehler auf eine kleine Menge standardisierter Meldungen wie „Daten konnten nicht geladen werden. Bitte versuchen Sie es erneut.“ Bieten Sie wenn möglich eine Retry‑Aktion an und loggen Sie detaillierte Fehler außerhalb des Widgets.

Beispiel: Ein ApprovalBadge‑Widget sollte nicht selbst entscheiden, ob eine Rechnung freigegeben werden darf. Lassen Sie die Seite status und canApprove berechnen. Das Badge emittiert approve und die Seite führt die echte Regel aus und ruft das Backend an, dann gibt sie sauberen Success‑ oder Error‑State zurück in die UI.

Häufige Fehler, die nach der nächsten Regeneration Schmerzen verursachen

Die meisten Probleme haben nichts mit Vue an sich zu tun. Sie entstehen, weil Custom‑Arbeit in Orte fließt, die der Generator kontrolliert, oder weil man sich auf Details verlässt, die sich ändern.

Fehler, die ein kleines Widget in dauerhafte Wartungsarbeit verwandeln:

• Generierte Vue‑Dateien direkt bearbeiten und nicht dokumentieren, was geändert wurde.
• Globales CSS oder breite Selektoren verwenden, die andere Screens beeinflussen, wenn sich Markup verschiebt.
• Generierten State direkt lesen oder mutieren, sodass eine harmlose Umbenennung das Widget bricht.
• Zu viele seiten‑spezifische Annahmen in eine Komponente packen.
• Die API (Props/Events) der Komponente ohne Migrationsplan ändern.

Ein typisches Szenario: Sie fügen ein Custom‑Table‑Widget hinzu und es funktioniert. Einen Monat später führt eine generierte Layout‑Änderung dazu, dass Ihre globale .btn‑Regel plötzlich Anmelde‑ und Admin‑Seiten beeinflusst. Oder ein Datenobjekt ändert sich von user.name zu user.profile.name und das Widget schlägt still fehl. Das Widget ist nicht das Problem — die Abhängigkeit von instabilen Details ist es.

Zwei Gewohnheiten verhindern das meiste:

Erstens: Behandeln Sie generierten Code als read‑only und halten Sie Custom‑Dateien getrennt mit einer klaren Import‑Grenze.

Zweitens: Halten Sie den Komponentenvertrag klein und explizit. Wenn Sie ihn weiterentwickeln müssen, fügen Sie eine einfache Versions‑Prop hinzu (z. B. apiVersion) oder unterstützen Sie für eine Release‑Phase beide Prop‑Formen.

Schnellcheckliste bevor Sie ein Custom‑Component ausliefern

Bevor Sie ein maßgeschneidertes Widget in eine generierte Vue3‑App mergen, machen Sie einen kurzen Realitätstest. Es sollte die nächste Regeneration ohne Heldentaten überstehen und von anderen wiederverwendet werden können.

• Regenerate‑Test: Führen Sie eine volle Regeneration und einen Rebuild durch. Mussten Sie eine generierte Datei erneut editieren? Dann ist die Grenze falsch.
• Klare Ein‑ und Ausgänge: Props rein, Emits raus. Vermeiden Sie magische Abhängigkeiten wie DOM‑Grabs oder Annahmen über einen spezifischen Seiten‑Store.
• Style‑Containment: Scope Styles und verwenden Sie ein klares Klassenpräfix (z. B. timeline-).
• Alle Zustände sehen gut aus: loading, error und empty states sollten vorhanden und sinnvoll sein.
• Wiederverwendung ohne Kopieren: Bestätigen Sie, dass Sie das Widget auf einer zweiten Seite per Props und Event‑Handler verwenden können, ohne interne Dateien zu kopieren.

Ein schneller Validierungstest: Stellen Sie sich vor, Sie fügen das Widget einer Admin‑Seite und dann einer Customer‑Portal‑Seite hinzu. Funktioniert beides mit reinem Prop‑ und Event‑Handling? Dann sind Sie in einer sicheren Zone.

Ein realistisches Beispiel: Ein Timeline‑Widget ins Dashboard bringen

Support‑Teams wollen oft einen Screen, der die Geschichte eines Tickets erzählt: Statuswechsel, interne Notizen, Kundenantworten und Zahlungs‑ oder Lieferereignisse. Ein Timeline‑Widget passt gut, aber Sie wollen keine generierten Dateien editieren und Ihre Arbeit bei der nächsten Regeneration verlieren.

Der sichere Weg ist, das Widget außerhalb der generierten UI zu isolieren und es über einen dünnen Wrapper in die Seite zu setzen.

Der Widget‑Vertrag

Halten Sie ihn einfach und vorhersagbar. Der Wrapper übergibt z. B.:

• ticketId (string)
• range (letzte 7 Tage, letzte 30 Tage, benutzerdefiniert)
• mode (compact vs. detailed)

Das Widget emittiert:

• select, wenn der Nutzer ein Ereignis anklickt
• changeFilters, wenn der Nutzer Range oder Mode anpasst

So weiß das Widget nichts über das Dashboard, Datenmodelle oder wie Requests gemacht werden. Es rendert die Timeline und meldet Nutzeraktionen.

Wie der Wrapper die Seite verbindet

Der Wrapper sitzt neben dem Dashboard und übersetzt Seitendaten in den Vertrag. Er liest die aktuelle Ticket‑ID aus dem Seiten‑State, konvertiert UI‑Filter in einen range und mappt Backend‑Records in das Event‑Format, das das Widget erwartet.

Emittiert das Widget select, kann der Wrapper ein Detail‑Panel öffnen oder eine Seitenaktion auslösen. Bei changeFilters aktualisiert der Wrapper die Seitenfilter und lädt Daten neu.

Wenn das Dashboard neu generiert wird, bleibt das Widget unberührt, weil es außerhalb der generierten Dateien lebt. Meist müssen Sie nur den Wrapper anpassen, falls die Seite ein Feld umbenennt oder Filter anders speichert.

Test‑ und Release‑Gewohnheiten, die Überraschungen vermeiden

Custom‑Components versagen meistens auf banale Weise: Eine Prop‑Form ändert sich, ein Event feuert nicht mehr, oder ein regenerierter Page‑Rerender passiert öfter als erwartet. Einige Gewohnheiten fangen diese Probleme früh ab.

Lokales Testen: Grenzbrüche früh bemerken

Behandeln Sie die Grenze zwischen generierter UI und Widget wie eine API. Testen Sie das Widget ohne die ganze App zuerst, mit hartkodierten Props, die dem Vertrag entsprechen.

Rendern Sie es mit „Happy‑Path“‑Props und mit fehlenden Werten. Simulieren Sie Schlüsselereignisse (Speichern, Abbrechen, Auswahl) und bestätigen Sie, dass der Parent korrekt reagiert. Testen Sie langsame Daten und kleine Bildschirme. Verifizieren Sie, dass es keinen Global‑State schreibt, sofern das nicht Teil des Vertrags ist.

Wenn Sie auf einer AppMaster Vue3‑App bauen, führen Sie diese Prüfungen aus, bevor Sie irgendetwas regenerieren. Es ist einfacher, einen Grenzfehler zu diagnostizieren, wenn nicht zwei Dinge gleichzeitig geändert wurden.

Regression nach Regeneration: Was Sie zuerst erneut prüfen sollten

Nach jeder Regeneration prüfen Sie die Berührungspunkte: Werden dieselben Props übergeben und werden dieselben Events noch behandelt? Dort zeigt sich Fehler meist zuerst.

Halten Sie die Einbindung vorhersehbar. Vermeiden Sie fragile Imports, die von Dateipfaden abhängen, die sich verschieben können. Nutzen Sie einen stabilen Einstiegspunkt für Ihre Custom‑Components.

Für Produktion fügen Sie leichtgewichtige Logs und Error‑Captures im Widget hinzu:

• Mount‑Log mit wichtigen (sanitized) Props
• Vertragsverletzungen (fehlende Pflicht‑Prop, falscher Typ)
• Fehlgeschlagene API‑Aufrufe mit kurzem Fehlercode
• Unerwartete Empty States

Wenn etwas kaputtgeht, wollen Sie schnell beantworten können: Hat die Regeneration die Inputs verändert, oder hat das Widget sich verändert?

Nächste Schritte: Das Muster im ganzen App wiederholbar machen

Wenn das erste Widget funktioniert, ist der eigentliche Gewinn, das Muster wiederholbar zu machen, damit das nächste kein One‑Off‑Hack wird.

Erstellen Sie einen kleinen internen Standard für Widget‑Verträge und dokumentieren Sie ihn dort, wo Ihr Team Notizen ablegt. Halten Sie es einfach: Namenskonvention, required vs optional Props, ein kleines Event‑Set, Fehlerverhalten und klare Ownership (was in generierter UI lebt vs. im Custom‑Ordner).

Schreiben Sie die Boundary‑Regeln in klarer Sprache auf: bearbeite keine generierten Dateien, halte Custom‑Code isoliert, und übergib Daten nur via Props und Events. Das verhindert den „Quick Fix“, der zur permanenten Wartungssteuer wird.

Vor dem Bau des zweiten Widgets führen Sie eine kleine Regeneration‑Probe durch. Ship das erste Widget und regenerieren Sie mindestens zweimal im Rahmen normaler Änderungen (eine Label‑Änderung, Layout‑Änderung, neues Feld) und bestätigen Sie, dass nichts bricht.

Wenn Sie AppMaster nutzen, funktioniert es oft am besten, die meiste UI und Logik in den visuellen Editoren zu halten (UI‑Builder, Business Process Editor und Data Designer). Bewahren Sie benutzerdefinierte Vue‑Komponenten für wirklich maßgeschneiderte Widgets auf, die die Editoren nicht ausdrücken können — etwa spezielle Timelines, interaktive Charts oder ungewöhnliche Eingabesteuerungen. Wenn Sie einen sauberen Ausgangspunkt für diesen Ansatz wollen, ist AppMaster auf appmaster.io um Regeneration herum konzipiert, sodass isolierte Custom‑Widgets natürlich in den Workflow passen.