Entitäts-Hooks

Überblick

Die Entitäts-Hooks sind generierte React-Hooks, die einen vereinfachten, typsicheren Zugriff auf die von den Entitätsanbietern verwalteten Daten und Logik bieten. Untergeordnete Komponenten des Entitätsanbieters können diese Hooks nutzen, um den React-Kontext der Entität einfach zu lesen. Dadurch erhalten Komponenten Zugriff auf den aktuellen React-Zustand, schemabezogene Informationen und Validierungsergebnisse. Sowohl auf Entitätsebene als auch auf Einzelfeldebene verfügbar.

Note: Entitäts-Hooks für JobLines-Entitäten unterscheiden sich in ihrem Verhalten wesentlich. Weitere Informationen finden Sie auf der Seite Arbeiten mit JobLines.

Verwenden von Entitäts-Hooks

Wie im Digital SDK UI Extensions API-Vertrag erläutert, erstellt der Jutro SDK-Generator ein Verzeichnis für jede Entität, die von den einzelnen verfügbaren APIs in einem generierten SDK verwendet wird. Sie können die Entitäts-Hooks aus dem Stammpfad des Entitätsverzeichnisses importieren.

Sie werden nach dem Muster use<entity-name> benannt und müssen als untergeordnete Komponenten des zugehörigen Entitätsanbieters verwendet werden.

// import path 'src/generated/JutroUtils/<sdk-name>/<api-name>/<entity-name>'
// for a "Contact" entity in the "account" API of an SDK named "PcSDK"
import {
  ContactProvider,
  useContact,
} from 'src/generated/JutroUtils/PcSDK/account/Contact';

export const ContactPage = (): JSX.Element => (
  <ContactProvider>
    <ContactForm />
  </ContactProvider>
);

const ContactForm = (): JSX.Element => {
  const {
    state,
    setState,
    schema,
    validationResult,
    showSchemaValidationErrors,
    fields,
  } = useContact();
  
  // ...
};

Rückgabewert

Die Entitäts-Hooks geben ein einzelnes Objekt mit den folgenden Eigenschaften zurück.

state und setState

Die state-Eigenschaft ist eine React-Zustandsvariable zum Speichern der aktuellen Daten der Entität und die setState-Eigenschaft ist eine React-State-Setter-Funktion, die verwendet werden kann, um den state zu ändern. Sie verwenden den entsprechenden Entitätstyp, der im Digital SDK verfügbar ist.

Note: Das Ändern der state-Entität löst aus, dass der Entitätsanbieter das Entitätsschema und die Validierungsfunktionen erneut ausführt.

Im folgenden Beispiel wird state und setState verwendet, um eine gesteuerte Eingabe für das displayName-Feld einer „Contact“-Entität zu rendern.

// ...
  const { state, setState } = useContact();

  return (
    <label>
      Enter your name:
      <input
        type="text"
        value={state.displayName}
        onChange={(e) =>
          setState((prev) => ({ ...prev, displayName: e.target.value }))
        }
      />
    </label>
  );
};

schema

Die schema-Eigenschaft ist der Rückgabewert des Aufrufs der Funktion getEntitySchema des Digital SDK.

Note: Der Entitätsanbieter führt die Schemafunktion für die entsprechende Entität bei jedem Rendering aus, übergibt die aktuelle state-Entität als Argument und stellt sicher, dass die Schemaregeln mit diesem Status erneut ausgewertet werden.

Weitere Informationen zu den Entitätsschemas finden Sie in den Digital SDK-Dokumenten.

validationResult

Diese Eigenschaft enthält das Ergebnis der Ausführung der im Digital SDK verfügbaren Validierungsfunktion der Entität.

Note: Der Entitätsanbieter führt bei jedem Rendern die Validierungsfunktion für die entsprechende Entität aus und stellt so sicher, dass das validationResult mit dem aktuellen state übereinstimmt.

Wie in den Digital SDK-Dokumenten erläutert, gibt das Objekt validationResult an, ob die Entität isValid nach dem Anwenden der JSON-Schemavalidierung auf die aktuelle state-Entität ist, und stellt ein Array von errors bereit, falls diese nicht gültig ist.

showSchemaValidationErrors

Die Eigenschaft showSchemaValidationErrors stammt direkt aus der benutzerdefinierten Eigenschaft des Entitätsanbieters.

Dies ist ein Boolean-Wert, der von den generierten Feldkomponenten verwendet wird, um die Anzeige von Validierungsfehlern umzuschalten. Wenn showSchemaValidationErrors in Verbindung mit validationResult verwendet wird, können Sie Ihre benutzerdefinierten Komponenten mit diesem Verhalten der generierten Feldkomponenten synchronisieren.

fields

In diesen Fällen wird eine fields-Eigenschaft zur Verfügung stehen:

1. Das Entitätsschema ist ein JSONSchemaWithFields-Typ.
2. Das Entitätsschema ist ein JSONSchemaGW und die dangerouslyForceEntityFieldGeneration-Markierung wurde bei der Generierung verwendet.
3. Das Entitätsschema ist ein JSONSchemaCoverage-Typ.

Diese Eigenschaft ist ein Objekt mit so vielen Eigenschaften, wie JSONSchemaField-Objekte im Schema definiert sind, wobei der Feldname als Schlüssel verwendet wird.

const { fields } = useContact();
const { displayName, email, phoneNumber } = fields;

Note: Bei JSONSchemaCoverage-Typentitäten wird der Wert der selected-Eigenschaft zum zurückgegebenen fields-Objekt hinzugefügt.

Jobline-Entitäten können auch zusätzliche Felder generieren. Weitere Informationen finden Sie auf der Seite Arbeiten mit JobLines.

Als Wert enthält jede dieser Eigenschaften ein Objekt mit relevanten Informationen über das entsprechende Feld, extrahiert aus den im Entitätsanbieter verfügbaren Daten. Weitere Informationen zum Inhalt dieses Objekts finden Sie im Abschnitt Eigenschaften auf Feldebene.

Eigenschaften auf Feldebene

Diese Eigenschaften bieten direkten Zugriff auf feldbezogene Informationen und Logik, die bereits auf Entitätenebene vorhanden sind. Dies vereinfacht den Zugriff auf feldspezifische Details, da die Datenstruktur der Entität nicht mehr manuell durchlaufen werden muss.

state und setState

Diese sind Äquivalente zu den Eigenschaften state und setState auf Entitätenebene, zielen jedoch nur auf ein Feld in dem Status ab, wobei die Digital SDK-Typdefinition des entsprechenden Felds verwendet wird.

Wir können beispielsweise den Beispielcode aus den Abschnitten state und setState auf Entitätsebene so umschreiben, dass er die Feldebene state und setState wie folgt verwendet:

// ...
  const { fields } = useContact();
  const { displayName } = fields;
  const { state, setState } = displayName;

  return (
    <label>
      Enter your name:
      <input
        type="text"
        value={state}
        onChange={(e) => setState(e.target.value)}
      />
    </label>
  );
};

errors

Die errors-Eigenschaft des Felds ist eine gefilterte Version des errors-Arrays, das vom validationResult der Entität zurückgegeben wird. Dies schließt nur Mitglieder dieses Arrays ein, die sich auf das spezifische Feld beziehen.

Sie können es verwenden, um die für das Feld relevanten Fehlermeldungen zu erhalten.

fieldSchema

Die fieldSchema-Eigenschaft des Felds ist ein Shortcut zum Attribut properties.fieldName des Schemas der Entität.

Dies entspricht dem Zugriff auf die entsprechende Eigenschaft des schema der Entität.

const { schema } = usePhoneNumber();
const numberSchema = schema.properties.number;
//////
const { fields } = usePhoneNumber();
const { number } = fields;
const { fieldSchema: numberSchema } = number;

HTML-Eingabeeigenschaften

Dies sind praktische Shortcuts, die eine direkte Zuordnung zwischen den im schema der Entität verfügbaren Informationen und einem Satz von HTML-Standardattributen für Eingaben ermöglichen, wodurch der zum Rendern von Eingabefeldern erforderliche Transformationslogik reduziert wird.

• disabled wird auf true gesetzt, wenn das Feld als x-gw-forbidden gekennzeichnet ist.
• label ist der Wert von schema.properties.<field-name>.title.
• title ist der Wert von schema.properties.<field-name>.description.
• readOnly ist der Wert von schema.properties.<field-name>.readOnly.
• required wird auf gesetzt, true wenn das Feld mit einer der x-gw-requiredFor-Eigenschaften gekennzeichnet ist.
• maxLength ist der Wert der x-gw-maximum-Eigenschaft für dieses Feld, falls vorhanden.
• minLength ist der Wert der x-gw-minimum-Eigenschaft für dieses Feld, falls vorhanden.

// ...
  const { fields } = useContact();
  const { displayName } = fields;
  const {
    state,
    setState,
    required,
    disabled,
    label,
    title,
    readOnly,
    maxLength,
    minLength,
  } = displayName;

  return (
    <label>
      {label}
      <input
        type="text"
        value={state}
        onChange={(e) => setState(e.target.value)}
        required={required}
        disabled={disabled}
        title={title}
        readOnly={readOnly}
        maxLength={maxLength}
        minLength={minLength}
      />
    </label>
  );
};