Direkt zum Hauptinhalt

Manifest eines benutzerdefinierten Steuerelements

Schema-ID: custom-control-manifest@1 Maschinenlesbares Schema: custom-control-manifest.schema.json

Die maßgebliche Beschreibung eines benutzerdefinierten Steuerelements (im PCF-Stil, Abschnitt 6.3): das Module-Federation-Remote, das der Player für modellgesteuerte Apps anstelle eines nativen Feldeditors in einem Formular oder einer Ansicht einhängt. Ein Manifest wird identisch validiert, ob es über das Admin Control Center registriert, per direktem API-Aufruf übermittelt, von einem KI-Assistenten generiert oder in einem Lösungsimport mitgeliefert wird – die Regel des einen Validierungspfads (Abschnitt 6.7).

Es wird nicht von Hand geschrieben. Die Registrierung eines Steuerelements ist der Upload des Pakets, das @parsware/pack gebaut hat, und dieses Manifest wird aus der eigenen parsware.json dieses Archivs zusammengesetzt (§28). Das Folgende beschreibt die gespeicherte Form – zum Lesen einer exportierten Lösung oder zum Validieren einer, die Sie generiert haben.

Aufbau​

FeldTypPflichtHinweise
logicalNamestringjaMit Herausgeberpräfix, Snake-Case in Kleinbuchstaben (z. B. par_signature_pad). Wird über die Eigenschaft control des Felds an ein Formularfeld gebunden.
displayNamestringjaLesbarer Name, der in der Feldpalette des Formulardesigners angezeigt wird.
descriptionstring | nullneinKurzbeschreibung, die neben dem Steuerelement angezeigt wird.
scopestringjaDer globale Scope-Name des Module-Federation-Containers (eindeutig pro Remote), aus der mf-manifest.json des Builds gelesen statt neu eingetippt.
modulestringjaDer Pfad des bereitgestellten Moduls, das der Player lädt (z. B. ./Control). Muss mit ./ beginnen. Ebenfalls aus dem Build gelesen.
entryFileNamestringneinDie Einstiegsdatei des Containers im Paket (z. B. remoteEntry.js). Die Auslieferungs-URL wird aus der Umgebung, dem logischen Namen und diesem Wert berechnet – es gibt keine URL zu speichern. Leer im Hosted-Modus.
packageHashstring | nullneinSHA-256 in Kleinbuchstaben-Hex des Paketarchivs, aus dem das Steuerelement registriert wurde. Wird beim Import gegen die Bytes geprüft, die in einem Lösungspaket mitgereist sind, sodass ausgeliefert wird, was exportiert wurde. Null im Hosted-Modus.
remoteEntryUrlstring | nullneinNur im Hosted-Modus: eine absolute http(s)-URL zu einer extern ausgelieferten remoteEntry.js, für Hot Reload während der Entwicklung. Die Registrierung wird abgelehnt, sofern die Umgebung nicht zur Stufe Development gehört, und ein gehostetes Steuerelement reist nicht in einem Lösungspaket mit – sein Code gehört nicht der Plattform.
substitutesForstring[]jaDie Steuerelementtypen von Feldern, an die dieses Steuerelement gebunden werden kann: einer oder mehrere von Text, MultilineText, Number, Boolean, DateTime, Lookup, File, Image, Custom. Muss mindestens einen Eintrag enthalten. Die Feldpalette bietet das Steuerelement nur dort an, wo der Steuerelementtyp eines Felds passt. Es sind die Datentypfamilien, zu denen ein Feld gehört – nicht die Namen der eingebauten Steuerelemente, die eine Formularplatzierung wählt (TextArea, Toggle, Dropdown, …); das ist ein anderes Vokabular, das zufällig vier Namen mit diesem teilt.

Was es nicht mehr enthält​

requestedScopes und declaredEntities sind entfallen, und additionalProperties ist false, sodass ein Manifest, das eines davon noch enthält, abgewiesen statt stillschweigend ignoriert wird. Ein Steuerelement läuft mit den Berechtigungen der Person, die es verwendet (§24): Eine angeforderte Scope-Menge wurde immer nur mit der eigenen Sitzung des Benutzers geschnitten, konnte den Benutzer des Steuerelements also einschränken, aber nie erweitern, und die Liste der deklarierten Tabellen wurde von keinem einzigen Codepfad gelesen. Beide zu streichen, macht aus der Sicherheitsgeschichte einen Satz statt zweier Stellschrauben.

Auch ein verpflichtendes remoteEntryUrl ist entfallen. Das Bundle reist jetzt als Paket, das vom eigenen Ursprung der Plattform ausgeliefert wird; die URL wird also berechnet statt gespeichert (§28).

Der Vertrag des Steuerelements​

Das bereitgestellte Modul (./Control) ist eine einzelne React-Komponente, die den festen Vertrag ParswareControlProps aus @parsware/runtime-sdk implementiert:

interface ParswareControlProps {
  value: unknown;                     // the bound field's current value
  onChange: (next: unknown) => void;  // commit a new value back to the form
  fieldMetadata: FieldMetadata;       // the bound field's type/label/constraints
  context: RuntimeContext;            // the same auth/data/logging context apps get
}

Der Player liefert diese Props zur Renderzeit. Ein Steuerelement erreicht die Plattform ausschließlich über context (eine ParswareRuntime) – niemals durch einen direkten Aufruf des Gateways oder des Identity Service.

Wo es validiert wird​

  • Registrierung – der Application Layer validiert das Manifest gegen custom-control-manifest@1 und stellt sicher, dass logicalName mit dem Präfix des besitzenden Herausgebers beginnt, bevor er das Steuerelement in einer Umgebung erfasst.
  • Lösungsimport – jedes in einem Lösungspaket eingebettete Manifest wird gegen dasselbe Schema erneut validiert, bevor das Steuerelement in der Zielumgebung registriert wird.

Sicherheitshinweise​

Ein benutzerdefiniertes Steuerelement läuft im selben JavaScript-Realm wie die Shell (Module Federation, kein iframe – Abschnitt 6.3), daher wird die Vertrauensgrenze an anderer Stelle durchgesetzt:

  • Ein paketiertes Steuerelement wird vom eigenen Ursprung der Plattform ausgeliefert, es gibt also keinen externen Ursprung, der auf die Positivliste müsste. Die CSP-Positivliste gilt weiterhin für den Hosted-Modus – die einzige Form, deren Bundle ein Ersteller auf eine beliebige Adresse richten kann, und die außerhalb einer Entwicklungsumgebung abgelehnt wird.
  • Das Archiv wird vor dem Speichern geprüft: Größe, Dateianzahl, entpackte Größe, dass kein Eintrag einen Pfad außerhalb seines eigenen Ordners nennt und dass jede Datei einen Typ hat, den die Plattform ausliefert.
  • Das Steuerelement ist nur ladbar, wenn eine Lösung es in diese Umgebung bereitgestellt hat, und der Hash des Pakets wird beim Import und nochmals vor jedem Entpacken auf die Festplatte überprüft.
  • Jeder Datenaufruf, den es über das Runtime SDK tätigt, wird serverseitig gegen das App Context Token autorisiert, das die eigenen Scopes des Benutzers trägt. Ein Steuerelement kann genau das tun, was die Person tun kann, die es verwendet, und kein Feld dieses Manifests ändert daran etwas.

Verwandt​