Referencia de reglas de campo

Esta es la superficie completa que puede invocar una regla de campo. Todo lo que aparece aquí está en alcance dentro del cuerpo de una regla: sin importaciones ni configuración previa.

¿Es tu primer contacto con las reglas? Lee primero Reglas de campo. Cubre los eventos, la nomenclatura de las funciones y cómo construir la clave de un campo — las piezas que necesitas antes de que esto sea útil.

El objeto del campo

Cada campo del formulario se alcanza como field.<claveDelCampo>. Dentro de un manejador OnChange, OnBlur, OnFocus u OnClick, el argumento que recibes es ese mismo objeto, así que value.getValue y field.<su propia clave>.getValue son equivalentes.

Leer y escribir el valor

Miembro	Tipo	Qué hace
`getValue`	Propiedad	El valor actual del campo. El tipo depende del campo.
`setValue({ value, onchange })`	Método	Asigna el valor. `onchange: true` vuelve a ejecutar la regla OnChange del campo; `false` no.
`setValueAsync({ value, onchange }, options?)`	Método	Igual, pero retorna una promesa que se resuelve cuando el campo termina de asentarse. Úsalo en campos de tipo formulario, con `await`. Acepta `{ timeoutMs }`.
`getObject`	Propiedad	El objeto seleccionado completo en campos de selector y foráneos, no solo el id.
`getObjectAsync(options?)`	Método	Resuelve `getObject` cuando ya está poblado. Acepta `{ timeoutMs }`.
`e`	Propiedad	La carga útil del evento actual. Su contenido depende del tipo de campo.
`applyPatch(value)`	Método	Escribe el valor directamente en el registro, sin esperar a un guardado.

setValue recibe un objeto, no un valor suelto: setValue({ value: 'abc', onchange: false }). Pasar un valor suelto no hace nada.En campos foráneos y de selector, pasa solo el id, no un objeto armado a mano.

getValue sobre un campo de tabla o de detalle no devuelve los datos pintados en él. Si necesitas esos datos al guardar, reconstrúyelos en el manejador de guardado en lugar de leerlos de vuelta.

Estado de validación

Miembro	Tipo	Qué hace
`error`	Propiedad	El estado de error actual: `{ valid, message }`.
`setError({ valid, message })`	Método	Asigna el estado de error. `valid: false` marca el campo como inválido y muestra el mensaje.
`isMandatory`	Propiedad	Si el campo es obligatorio en este momento.
`setIsMandatory(bool)`	Método	Hace el campo obligatorio u opcional.
`onValidate(value)`	Método	Ejecuta la validación del campo y retorna `{ valid, message? }`.
`setOnValidate(fn)`	Método	Reemplaza la lógica de validación del campo.

Visibilidad e interacción

Miembro	Tipo	Qué hace
`visible`	Propiedad	Si el campo está visible en este momento.
`setVisible(bool)`	Método	Muestra u oculta el campo. Sigue montado.
`render`	Propiedad	Si el campo está renderizado en este momento.
`setRender(bool)`	Método	Monta o desmonta el campo por completo.
`enabled`	Propiedad	Si el campo acepta entrada.
`setEnabled(bool)`	Método	Habilita o deshabilita la entrada.
`focus()`	Método	Mueve el foco al campo, cambiando de pestaña si hace falta.

setVisible y setRender no tienen efecto en contexto de tabla. Para comportamientos que deban funcionar en una tabla, cambia valores, errores o el estado habilitado.

Identidad

Miembro	Tipo	Qué hace
`dbname`	Propiedad	El nombre con el que se almacena el campo.
`clientname`	Propiedad	El nombre visible del campo.

Eventos

Invoca los miembros on* para volver a disparar el evento propio de un campo. Invoca los miembros setOn* para reemplazar un manejador en tiempo de ejecución; normalmente las reglas se adjuntan desde el Diseñador de páginas, así que son poco frecuentes dentro del cuerpo de una regla.

Miembro	Qué hace
`onChange(e)`	Ejecuta el manejador OnChange del campo.
`onBlur(e)`	Ejecuta el manejador OnBlur del campo.
`onFocus(e)`	Ejecuta el manejador OnFocus del campo.
`onClick()`	Ejecuta el manejador OnClick del campo.
`setOnChange(fn)`	Reemplaza el manejador OnChange.
`setOnBlur(fn)`	Reemplaza el manejador OnBlur.
`setOnFocus(fn)`	Reemplaza el manejador OnFocus.
`setOnClick(fn)`	Reemplaza el manejador OnClick.

Nunca vuelvas a disparar el evento propio de un campo desde las reglas que escriben en él. Si varios campos origen llaman field.<destino>.onChange(), el OnChange del destino se convierte en el manejador de composición, y escribir directamente en el destino sobrescribe lo que ingresa el usuario. Escribe con setValue({ onchange: false }).

Los manejadores OnChange tienen un retardo de 500 ms. Asigna _delay a la función del manejador para cambiarlo — por ejemplo myHandler._delay = 0 para no tener retardo.

Propiedades adicionales

setProperties(props) define opciones propias del tipo de campo. En un campo de fecha, por ejemplo, restringe qué fechas se pueden elegir:

field.order_delivery_date.setProperties([
  { type: 'after',  date: new Date(2026, 0, 1) },
  { type: 'before', date: new Date(2026, 0, 15) },
  { type: 'exact',  date: new Date(2026, 0, 20) },
  { type: 'range',  start: new Date(2026, 1, 1), end: new Date(2026, 1, 10) }
])

Helpers del formulario

failfast.myFormHelpers controla el formulario como un todo. Es lo que usan las reglas OnLoad, OnSubmit y OnDelete.

Miembro	Qué hace
`getFormData()`	El objeto que el formulario va a enviar.
`getRecord()`	El registro que se está editando. `getRecord().id` es falsy en modo creación y el id del registro en modo edición.
`setNewRecord(id)`	Asigna el id del registro después de guardar.
`handleSubmit()`	Envía el formulario. Se resuelve con el registro guardado, o con `{ error: true, message }` si falla.
`setHandleSubmit(fn)`	Reemplaza el manejador de guardado del formulario.
`setEnabledSubmit(bool)`	Habilita (`true`) o deshabilita (`false`) el botón de guardar.
`setOnLoad(fn)`	Reemplaza el manejador de carga del formulario.
`runOnLoad()`	Ejecuta el manejador de carga del formulario.
`invalidateRelatedQueries()`	Refresca los datos relacionados con este formulario.
`windowViewState(false)`	Cierra la ventana del formulario actual.

handleSubmit() puede fallar. Verifica siempre el resultado antes de continuar, sobre todo en un formulario embebido, donde a un guardado fallido le seguirían pasos que asumen que funcionó:

const record = await failfast.myFormHelpers.handleSubmit()
if (!record || record.error) return

Usa throw result en lugar de return cuando la regla que lo rodea también deba detenerse.

Helpers de la nota

failfast.myNoteHelpers lee y escribe la nota del formulario. Los tres son asíncronos: si el editor todavía no se ha montado, la operación espera y se aplica cuando lo haga.

Miembro	Qué hace
`isReady()`	Se resuelve cuando el editor de notas está disponible.
`setContent(content)`	Reemplaza toda la nota. Acepta markdown o bloques.
`append(content)`	Agrega contenido al final de la nota. Acepta markdown o bloques.

Escribir en la nota cuenta como una edición del usuario y se guarda igual. Una regla OnLoad que escriba en la nota va a sobrescribir lo que ya está guardado, a menos que cortes primero en modo edición:

if (failfast.record) return // solo en creación
await failfast.myNoteHelpers.append('- Observación adicional')

Contexto del espacio de trabajo

failfast lleva la información de quién está trabajando y en qué contexto. field y failfast son el mismo objeto, así que cualquiera de los dos nombres funciona.

Miembro	Qué contiene
`failfast.company`	La empresa actual.
`failfast.user`	El usuario con la sesión iniciada.
`failfast.isAdmin`	Si ese usuario es administrador.
`failfast.userActions`	Las acciones disponibles para el usuario.
`failfast.record`	El id del registro que se está editando.
`failfast.nameEntity`	El nombre de la entidad del formulario.
`failfast.typeRender`	El contexto de renderizado: `'form'` o `'table'`.
`failfast.parentFormId`	El id compuesto del formulario padre, cuando existe.

Protege con if (failfast.typeRender === 'table') return el comportamiento que solo tenga sentido en un formulario completo. La misma regla se ejecuta en ambos contextos.

Acciones del contexto

Miembro	Qué hace
`failfast.loading(bool)`	Muestra u oculta la pantalla de carga.
`failfast.setEditEnabled(bool)`	Habilita o deshabilita el botón de editar. Solo en contexto de tabla.
`failfast.setViewEnabled(bool)`	Habilita o deshabilita el botón de ver. Solo en contexto de tabla.
`failfast.setDeleteEnabled(bool)`	Habilita o deshabilita el botón de eliminar. Solo en contexto de tabla.
`failfast.setNewEnabled(bool)`	Habilita o deshabilita el botón de nuevo registro. Solo en contexto de formulario. El nombre del miembro lleva la entidad a la que aplica.

Servicios y procesos

Miembro	Qué hace
`failfast.getIntegration(name, params)`	Invoca una integración configurada.
`failfast.process(id, name, params)`	Ejecuta un proceso.
`failfast.globalProcess(id, name, params)`	Ejecuta un proceso global.

Registros

Cuatro nombres le dan a una regla acceso a los campos; la diferencia está en de qué formulario son esos campos.

Registro	Alias	Alcanza	Duración
`field`	`failfast`	El formulario actual	Se limpia al desmontar el formulario
`fieldParent`	`failfastParent`	El formulario padre, o `null` si no hay	Sigue al formulario padre
`page`	`failfast2`	Todos los formularios montados: padre, detalle y embebidos	Sobrevive a la navegación

Son objetos vivos, así que todo lo que les asignes queda visible para cada regla que corra después. Ese es el mecanismo para compartir un helper entre reglas — consulta compartir lógica.

Las claves de page comparten espacio de nombres con los identificadores de formulario, así que pon tus helpers dentro de un contenedor como page.__helpers en lugar de dejarlos en el nivel superior.page nunca se limpia, así que un helper definido por un formulario sigue ahí después de navegar a otro. Reasígnalo siempre (page.__helpers.x = …) en lugar de definirlo solo cuando falte, o se usará una versión obsoleta de un formulario anterior.

Objetos integrados

Están en alcance en el cuerpo de toda regla.

Nombre	Qué es
`axiosFailFast`	Cliente de solicitudes para los datos de Fail Fast, con el contexto del espacio de trabajo aplicado.
`axios`	Cliente de solicitudes simple para servicios externos.
`apis`	Endpoints con nombre de las entidades del espacio de trabajo, para usar con `axiosFailFast`.
`toast`	Muestra una notificación al usuario.
`formulajs`	Funciones de fórmula al estilo de una hoja de cálculo.
`postgresqlFunction`	Invoca una función almacenada de la base de datos.
`executeWorkflow`	Ejecuta un workflow.
`showComponent(name, props, options, callbacks)`	Abre un componente, como un diálogo o un formulario embebido.
`entityName`	El nombre de la entidad del formulario.
`getUUIDByNameEntity(name)`	Resuelve el nombre de una entidad a su identificador.
`getNameByUUIDEntity(id)`	Resuelve el identificador de una entidad a su nombre.
`XMLParser`	Analiza respuestas XML.
`companyId`	El identificador de la empresa actual.
`formId`	El identificador del formulario actual.
`isVirtual`	Si el formulario se renderiza de forma virtual.
`openedFrom`	Desde dónde se abrió el formulario.
`executeOnload`	Si el manejador de carga se ejecuta al compilar.
`waitForHelpersReady`	Espera hasta que los helpers del formulario estén disponibles.

await funciona en cualquier punto del cuerpo de una regla: el manejo asíncrono se aplica por ti.Carga los datos relacionados en una sola solicitud usando el parámetro fields en lugar de una solicitud por relación. fields=customer__name,customer__document_number avanza hacia adelante por las relaciones; una relación inversa regresa como arreglo. Los formatos de solicitud y respuesta están documentados en la Referencia de API.

Helpers compartidos

Estas funciones provienen del catálogo de reglas de tu espacio de trabajo y se pueden invocar por su nombre desde cualquier regla.

Helper	Úsalo en	Qué hace
`validateOnLoad(fields, record)`	OnLoad	Aplica valores iniciales y estado solo en modo creación. Cada entrada es `[campo, valorInicial, habilitado, visible]`.
`validateOnLoadUpdate(fields, record)`	OnLoad	Aplica estado solo en modo edición. Cada entrada es `[campo, habilitado, visible]` — sin valor inicial, porque lo aporta el registro.
`validateOnSubmit(fields, formelements, api, unique, recordId, …)`	OnSubmit	Valida los campos listados y guarda. Debe invocarse con `await`.
`validateNotNullField(event)`	Eventos de campo	Verifica que un campo tenga valor y asigna su estado de error.

El arreglo fields que le pasas a validateOnSubmit debe incluir todos los campos que el registro exige, no solo los que toca una condición. Lo que omitas no se valida, llega al guardado y falla allí sin un mensaje sobre el que el usuario pueda actuar.

Tu espacio de trabajo puede definir helpers de catálogo adicionales además de estos cuatro. Abre el menú Código en el Diseñador de páginas para ver cuáles están disponibles.

Configuración del selector

Una regla OnClick sobre un campo selector retorna un objeto de configuración. Todas las claves son opcionales: retorna solo lo que necesites.

Clave	Qué define
`endPoint`	La fuente de datos a consultar.
`id`	La columna que se usa como valor.
`display`	La columna que se muestra como etiqueta principal.
`subtitle`	La columna que se muestra como etiqueta secundaria.
`search`	La columna o columnas en las que busca el cuadro de búsqueda.
`filter`	Un filtro aplicado a la consulta.
`foreign`	La columna relacionada por la que filtrar.
`idForeign`	El identificador relacionado por el que filtrar.
`relations`	Columnas relacionadas adicionales que se deben resolver.
`multiple`	Si se pueden seleccionar varias opciones.
`viewAvatar`	Si se muestra la imagen referenciada como avatar.
`placeHolder`	El texto de marcador de posición.
`allowDelete`	Si cada selección tiene un botón para limpiarla.

Valores de retorno por evento

Evento	Debe retornar
Validation	`{ valid: boolean, message?: string }`
`visible`, `enabled`, `render`	Un booleano
OnClick sobre un selector	Un objeto de configuración del selector
Todos los demás eventos	Nada

Páginas relacionadas

Reglas de campo

Eventos, nomenclatura, claves de campo y los patrones en los que se usan estos métodos.

Diseñador de páginas

Donde se adjuntan las reglas, bajo el menú Código.

Primeros pasos

Fundamentos de la plataforma

Construye y gestiona datos

Automatiza el trabajo

IA y comunicación

Operaciones de negocio

Finanzas

Transporte

Documentos y reportes

Administración del espacio de trabajo

Referencia de reglas de campo

El objeto del campo

Leer y escribir el valor

Estado de validación

Visibilidad e interacción

Identidad

Eventos

Propiedades adicionales

Helpers del formulario

Helpers de la nota

Contexto del espacio de trabajo

Acciones del contexto

Servicios y procesos

Registros

Objetos integrados

Helpers compartidos

Configuración del selector

Valores de retorno por evento

Páginas relacionadas

Reglas de campo

Diseñador de páginas

​El objeto del campo

​Leer y escribir el valor

​Estado de validación

​Visibilidad e interacción

​Identidad

​Eventos

​Propiedades adicionales

​Helpers del formulario

​Helpers de la nota

​Contexto del espacio de trabajo

​Acciones del contexto

​Servicios y procesos

​Registros

​Objetos integrados

​Helpers compartidos

​Configuración del selector

​Valores de retorno por evento

​Páginas relacionadas

Reglas de campo

Diseñador de páginas

El objeto del campo

Leer y escribir el valor

Estado de validación

Visibilidad e interacción

Identidad

Eventos

Propiedades adicionales

Helpers del formulario

Helpers de la nota

Contexto del espacio de trabajo

Acciones del contexto

Servicios y procesos

Registros

Objetos integrados

Helpers compartidos

Configuración del selector

Valores de retorno por evento

Páginas relacionadas