Direkt zum Hauptinhalt

Ein benutzerdefiniertes Steuerelement registrieren

Ziel​

Ein benutzerdefiniertes Steuerelement durch Hochladen seines Pakets in einer Umgebung installieren, damit es in einem Feld eines modellgesteuerten Formulars eingebunden werden kann.

Sie möchten wissen, wie Sie das Steuerelement bauen, statt eines zu installieren? Diese Seite setzt voraus, dass das Steuerelement bereits existiert und gepackt wurde. Wie Sie es schreiben – der feste Props-Vertrag, welche Feldtypen es ersetzen kann, welche Wertzustände es behandeln muss, Tests und Packen –, steht unter Ein benutzerdefiniertes Steuerelement bauen.

Voraussetzungen​

  • Sie sind als Plattformadministrator beim Admin Control Center angemeldet.
  • Ein Herausgeber und eine Lösung dieses Herausgebers existieren bereits.
  • Die Umgebung, in der Sie das Steuerelement installieren, ist aktiv.
  • Sie haben das Paket des Steuerelements – die .zip-Datei, die npm run pack im Projekt des Steuerelements erzeugt. Sie wird meist in den Ordner package/ dieses Projekts geschrieben und nach dem Steuerelement benannt, zum Beispiel par_signature_pad-1.2.3.zip.

Schritte​

  1. Wählen Sie in der Auswahl in der oberen Leiste die Umgebung aus, in der das Steuerelement installiert werden soll.
  2. Öffnen Sie Lösungen und dann die Lösung, zu der das Steuerelement gehört.
  3. Wählen Sie in der linken Navigation der Lösung Benutzerdefinierte Steuerelemente aus (oder die Karte Benutzerdefinierte Steuerelemente in der Lösungsübersicht). Die Seite listet die Steuerelemente auf, die diese Lösung in der ausgewählten Umgebung bereits installiert hat.
  4. Wählen Sie Neu aus. Am Bildschirmrand öffnet sich ein Seitenbereich.
  5. Wählen Sie die Paketdatei des Steuerelements aus.
  6. Wählen Sie Benutzerdefiniertes Steuerelement registrieren aus. Das Steuerelement erscheint in der Liste für diese Lösung und Umgebung, in der Lösungsübersicht unter Benutzerdefinierte Steuerelemente und in der Feldpalette des Formular-Designers.

Das ist das ganze Formular. Mehr ist nicht auszufüllen, weil das Paket bereits alles angibt: den logischen Namen und den Anzeigenamen des Steuerelements, den Module-Federation-Scope und das bereitgestellte Modul, die sein Build tatsächlich verwendet hat, die auszuliefernde Einstiegsdatei und die Feldtypen, die es ersetzen kann. Die letzten beiden wurden früher von Hand aus einer Bundler-Konfiguration abgeschrieben, und ein Fehler bei einem der beiden führte zu ein und demselben Symptom – das Steuerelement wurde einfach nicht geladen –, ohne Hinweis darauf, welcher der beiden falsch war.

Erneutes Hochladen ersetzt den installierten Build. Das ist der normale Ablauf bei der Arbeit an einem Steuerelement: ändern, npm run pack ausführen, erneut hochladen. Sie müssen die alte Registrierung nicht zuerst entfernen. Die Spalte Version zeigt, welcher Build installiert ist, sodass Sie prüfen können, ob das, was läuft, dem entspricht, was Sie zuletzt gepackt haben.

Um ein Steuerelement zu entfernen, aktivieren Sie das Kontrollkästchen seiner Zeile und wählen Entfernen aus. Dadurch wird es aus der Umgebung deinstalliert und sein gespeichertes Paket gelöscht; die Lösung behält ihren Komponentenverweis, weil das Steuerelement in anderen Umgebungen noch installiert sein kann.

Wo der Code des Steuerelements liegt​

Die Bytes des Pakets werden von der Plattform gespeichert und von ihrer eigenen Adresse ausgeliefert. Nichts wird von einem externen Host abgerufen, daher gilt:

  • Die Lösung ist in sich geschlossen – beim Exportieren wird der Code des Steuerelements mitgenommen, und ein Import in Test oder Produktion installiert ein funktionsfähiges Steuerelement statt eines Verweises auf den Ort, an dem es gebaut wurde;
  • es gibt keine URL für eine Positivliste und keine URL, die veralten kann.

Der Code eines Steuerelements muss nicht als Webressourcen hochgeladen werden. Webressourcen sind für eigenständige Dateien gedacht, die Sie erstellen und über ihren Namen referenzieren – ein Stylesheet, ein Bild, ein Skript –, nicht für die Build-Ausgabe eines Steuerelements.

Was im Hintergrund passiert​

Das Archiv wird geprüft, bevor etwas gespeichert wird: seine Größe, wie viele Dateien es enthält und wie groß es entpackt wird, dass keine enthaltene Datei einen Pfad außerhalb ihres eigenen Ordners angibt, dass jede Datei einem Typ entspricht, den die Plattform ausliefert, und dass sein Manifest dem veröffentlichten Paketschema entspricht. Danach wird der logische Name des Steuerelements gegen das Präfix des zuständigen Herausgebers geprüft.

Das Paket wird vollständig gespeichert und erst entpackt, wenn das Steuerelement zum ersten Mal tatsächlich angefordert wird. Deshalb funktioniert ein Steuerelement auch nach einem Neustart der Plattform weiter, und deshalb funktioniert es auf jedem Server gleich: Das gespeicherte Paket ist die eigentliche Kopie, und die entpackten Dateien sind nur ein Cache, der sich selbst neu aufbaut.

Die Installation des Steuerelements in einer Umgebung installiert es in keiner anderen; es gelangt dorthin, wenn seine Lösung exportiert und importiert wird.

Fehlerbehebung​

  • „Das Paket hat keine ‚parsware.json‘ im Stammverzeichnis.“ – Die hochgeladene Datei ist eine reine Build-Ausgabe statt eines Pakets. Bauen Sie es mit npm run pack im Projekt des Steuerelements.
  • „Das benutzerdefinierte Steuerelement … muss mit dem Herausgeberpräfix …_ beginnen.“ – Der logicalName in der package.json des Steuerelements beginnt nicht mit dem Präfix des zuständigen Herausgebers. Ändern Sie ihn dort und packen Sie erneut.
  • „Das Paket enthält … Dateien; das Maximum ist …“ – Fast immer ein node_modules-Ordner, der im Archiv gelandet ist. Packen Sie die Build-Ausgabe, nicht das Projekt.
  • „Das benutzerdefinierte Steuerelement … ist in dieser Umgebung bereits durch eine andere Lösung installiert.“ – Der logische Name ist vergeben. Benennen Sie das Steuerelement um oder entfernen Sie die andere Registrierung.
  • „Die Umgebung … ist nicht aktiv.“ – Warten Sie, bis die Bereitstellung der Umgebung abgeschlossen ist, oder wählen Sie eine andere Umgebung.

Während Sie das Steuerelement schreiben​

Für jede Änderung ein Paket hochzuladen ist eine langsame Schleife. In einer Entwicklungsumgebung bietet Neu eine zweite Wahl, Laufenden Entwicklungsserver verwenden: Geben Sie die Adresse ein, die npm run dev ausgibt, und wählen Sie Benutzerdefiniertes Steuerelement registrieren. Name und Federation-Einstellungen des Steuerelements werden vom Entwicklungsserver gelesen, und Formulare laden das Steuerelement von dort. Eine gespeicherte Änderung ist also sichtbar, sobald ein Formular das nächste Mal geöffnet wird. Die Spalte Version zeigt Gehostet (Entwicklung), solange es so registriert ist.

  • Ist das Steuerelement bereits installiert, entfernen Sie es zuerst. Ein Entwicklungsserver wird unter dem logischen Namen des Steuerelements registriert, das gebundene Formular verwendet ihn also weiter.
  • Wenn Sie fertig sind, laden Sie das Paket hoch. Es ersetzt die Registrierung des Entwicklungsservers, und die Spalte Version zeigt wieder den Build.

Außerhalb einer Entwicklungsumgebung erscheint die Wahl nicht: Ein so registriertes Steuerelement hat kein Paket, sein Code würde also nicht mit der Lösung reisen. Wie Sie das Projekt dafür einrichten, steht unter Ein benutzerdefiniertes Steuerelement erstellen.

Verwandte Szenarien​

  • Ein benutzerdefiniertes Steuerelement bauen.
  • Ein benutzerdefiniertes Steuerelement an ein Feld binden.
  • Eine benutzerdefinierte React-App registrieren.
  • Eine Lösung erstellen.