Saltar al contenido principal

Ganchos de entidad

Descripción general​

Los ganchos de entidad son ganchos de React generados que proporcionan un acceso simplificado y con seguridad de tipos a los datos y la lógica administrados por los proveedores de entidad. Los componentes secundarios del proveedor de entidad pueden aprovechar estos ganchos para leer fácilmente el contexto de React de la entidad. Esto otorga a los componentes acceso al estado actual de React, a la información relacionada con el esquema y a los resultados de validación; disponibles tanto al nivel de la entidad como al del campo individual.

Note: Los ganchos de entidad para las entidades JobLines tienen algunas diferencias clave en su comportamiento. Para obtener más información, consulte la página Cómo trabajar con JobLines.

Uso de ganchos de entidad​

Como se explica en Contrato de la API de extensiones de la interfaz de usuario del SDK de Digital, el generador del SDK de Jutro crea un directorio para cada entidad utilizada por cada una de las API disponibles en un SDK generado. Puede importar los ganchos de entidad desde la ruta raíz del directorio de entidades.

Se nombran siguiendo el patrón use<entity-name>, y deben ser utilizados por componentes secundarios de su proveedor de entidad asociado.

// 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();
  
  // ...
};

Devolver valor​

Los ganchos de entidad devuelven un solo objeto con las siguientes propiedades.

state y setState​

La propiedad state es una variable de estado de React que almacena los datos actuales de la entidad, y la propiedad setState es una función de establecimiento de estado de React que se puede utilizar para cambiar el state. Utilizan el tipo de entidad correspondiente disponible en el SDK de Digital.

Note: Si se cambia la entidad state, se activará el proveedor de la entidad para que vuelva a ejecutar las funciones de esquema y de validación de la entidad.

En el siguiente ejemplo se utiliza state y setState para renderizar una entrada controlada para el campo displayName de una entidad “Contact”.

// ...
  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​

La propiedad schema es el valor devuelto tras la llamada a la función getEntitySchema del SDK de Digital.

Note: El proveedor de la entidad ejecuta la función de esquema para la entidad correspondiente en cada renderización, pasa el state actual como argumento y se asegura de que las reglas del esquema se vuelvan a evaluar con este estado.

Para obtener más información sobre los esquemas de entidad, consulte los documentos del SDK de Digital.

validationResult​

Esta propiedad contiene el resultado de ejecutar la función de validación de la entidad disponible en el SDK de Digital.

Note: El proveedor de la entidad ejecuta la función de validación para la entidad correspondiente en cada renderizado, y se asegura de que validationResult esté actualizado con el state actual.

Como se explica en los documentos del SDK de Digital, el objeto validationResult indica si la entidad isValid después de aplicar la validación del esquema JSON al state actual y proporciona una matriz de errors en caso de que no sea válida.

showSchemaValidationErrors​

La propiedad showSchemaValidationErrors proviene directamente de la propiedad definida por el usuario del proveedor de la entidad.

Este es un valor booleano utilizado por los componentes de campo generados para alternar la visualización de errores de validación. Si se utiliza showSchemaValidationErrors junto con validationResult, podrá sincronizar los componentes personalizados con este comportamiento de los componentes de campo generados.

fields​

En estos casos habrá una propiedad fields que estará disponible:

  1. El esquema de la entidad es un tipo JSONSchemaWithFields.
  2. El esquema de la entidad es un JSONSchemaGW y el indicador dangerouslyForceEntityFieldGeneration se usó en la generación.
  3. El esquema de la entidad es un tipo JSONSchemaCoverage.

Esta propiedad es un objeto con tantas propiedades como objetos JSONSchemaField se definan en el esquema y que utiliza el nombre del campo como clave.

const { fields } = useContact();
const { displayName, email, phoneNumber } = fields;
Note: Para las entidades de tipo JSONSchemaCoverage, el valor de la propiedad selected se agregará al objeto de campos devueltos.

Las entidades Jobline también pueden generar campos adicionales. Para obtener más información, consulte la página Cómo trabajar con JobLines.

Como valor, cada una de estas propiedades contiene un objeto con información relevante sobre el campo correspondiente, extraída de los datos disponibles en el proveedor de la entidad. Encontrará más información sobre el contenido de este objeto en la sección de propiedades al nivel del campo.

Propiedades al nivel del campo​

Estas propiedades proporcionan acceso directo a la información relacionada con el campo y a la lógica que ya está disponible al nivel de la entidad. Esto simplifica el acceso a los detalles específicos del campo, ya que elimina la necesidad de atravesar manualmente la estructura de datos de la entidad.

state y setState​

Son equivalentes a las propiedades state y setState al nivel de la entidad, pero su objetivo es un solo campo en el estado mediante la definición de tipo del SDK de Digital del campo correspondiente.

Por ejemplo, podemos volver a escribir el código de muestra desde la sección state y setState al nivel de la entidad para usar state y setState al nivel del campo así:

// ...
  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​

La propiedad errors del campo es una versión filtrada de la matriz errors devuelta por validationResult de la entidad. Incluirá solo a los miembros de esa matriz que se relacionan con el campo específico.

Puede usarla para obtener los mensajes de error relevantes para el campo.

fieldSchema​

La propiedad fieldSchema del campo es un acceso directo al atributo properties.fieldName del esquema de la entidad.

Es equivalente a acceder a la propiedad correspondiente del schema de la entidad.

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

Propiedades de entrada HTML​

Son accesos directos convenientes que proporcionan asignación directa entre la información disponible en el schema de la entidad y un conjunto de atributos estándares HTML para las entradas, lo que reduce la cantidad de lógica de transformación necesaria para renderizar los campos de entrada.

  • disabled se establece en true si el campo está marcado como x-gw-forbidden.
  • label es el valor de schema.properties.<field-name>.title.
  • title es el valor de schema.properties.<field-name>.description.
  • readOnly es el valor de schema.properties.<field-name>.readOnly.
  • required se establece en true si el campo está marcado con una de las propiedades x-gw-requiredFor.
  • maxLength es el valor de la propiedad x-gw-maximum para este campo, si está presente.
  • minLength es el valor de la propiedad x-gw-minimum para este campo, si está presente.
// ...
  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>
  );
};