Copy page

Cycle d'évaluation

Le moteur ne suit pas les champs concernés par une modification. Chaque fois que quelque chose change, il exécute une passe d'évaluation complète sur tout le formulaire, toujours dans le même ordre. Connaître cet ordre explique l'essentiel de ce que vous observez à l'exécution : pourquoi un champ calculé peut piloter la visibilité, pourquoi un champ masqué compte toujours dans un calcul et quand les gestionnaires d'événements s'exécutent.

Créer un moteur

createFormEngine({ schema, initialValues }) prépare le formulaire une seule fois :

1. Il valide le schéma et lève une erreur s'il n'est pas valide. Voir Validation du schéma.
2. Il renseigne les valeurs : d'abord les initialValues que vous passez, puis le default_value de chacun des autres champs.
3. Il détermine de quels champs dépend chaque champ calculé. Cela se fait une seule fois, et non à chaque évaluation.
4. Il exécute form.events.code une fois pour enregistrer les gestionnaires d'événements. Aucun événement n'est déclenché à ce stade.

Créer un moteur n'évalue pas le formulaire. La visibilité, le caractère obligatoire et les erreurs restent vides jusqu'au premier appel à engine.eval(). Les bindings officiels l'appellent juste après avoir créé le moteur.

Une passe d'évaluation

engine.eval() exécute ces étapes dans l'ordre, à chaque fois :

Étape	Ce qui se passe	Résultat dans l'état
1. Calculs	Chaque CalculatedField exécute son expression calculate, dépendances d'abord	values
2. Caractère requis	required_conditions est vérifié, sinon l'indicateur statique required est utilisé	required
3. Visibilité	visible_conditions est vérifié, sinon l'indicateur statique visible est utilisé	visible
4. Lecture seule	read_only_conditions est vérifié, sinon l'indicateur statique read_only est utilisé	read_only
5. Validation	La valeur de chaque champ est vérifiée selon ses propres règles, comme pattern ou une plage numérique	errors

Après la passe, engine.getState() renvoie le résultat. Les mêmes valeurs produisent toujours le même état, quel que soit l'ordre dans lequel l'utilisateur les a saisies.

Ce que l'ordre implique pour votre schéma

• Les conditions voient les valeurs calculées. Les calculs s'exécutent en premier : un visible_conditions ou un required_conditions peut donc référencer un CalculatedField et obtient toujours sa valeur actuelle.
• Les calculs ignorent la visibilité. Masquer un champ n'efface pas sa valeur. La valeur d'un champ masqué reste dans values et compte toujours dans tout calcul qui la référence.
• La validation couvre tous les champs. Les erreurs de valeur sont aussi calculées pour les champs masqués. Un champ obligatoire vide n'est pas une erreur dans errors : c'est le renderer ou votre application qui décide s'il bloque la soumission. Voir Champs obligatoires et soumission.
• Les conditions sur les champs à choix comparent les valeurs sélectionnées. Une condition sur un champ à choix compare la value du choix sélectionné, et non l'objet stocké en entier. Voir Conditions et opérateurs.

Les sections suivent leurs enfants

La visibilité est évaluée des champs les plus internes vers l'extérieur. Une Section ou une RepeatableSection dont tous les enfants sont masqués est elle aussi masquée, quels que soient ses visible ou visible_conditions. Si au moins un enfant est visible, les réglages propres à la section s'appliquent.

Quand une valeur change

Le moteur n'a pas d'étape de « mise à jour » distincte. Quand un utilisateur modifie un champ, les bindings officiels :

1. Écrivent la nouvelle valeur dans les valeurs du moteur.
2. Exécutent engine.eval(), qui répète la passe complète décrite ci-dessus.
3. Publient le nouvel état dans l'interface.
4. Déclenchent change pour le champ modifié, ce qui exécute tout gestionnaire ON("change", ...) correspondant.

Les gestionnaires d'événements ne modifient jamais le formulaire eux-mêmes. Ils renvoient une liste d'opérations, comme SETVALUE ou ALERT, et le host les applique. Quand le host applique un SETVALUE, il écrit la valeur et exécute de nouveau eval(), mais il ne déclenche pas d'autre événement change. Un gestionnaire ne peut donc pas lancer une chaîne d'événements de modification en définissant d'autres champs.

Utiliser le moteur sans renderer

Si vous pilotez le moteur vous-même, suivez la même séquence que les bindings :

Code
import { createFormEngine } from "form0-core"

const engine = createFormEngine({ schema, initialValues: { quantity: 2 } })
engine.eval()

// When the user changes a value:
engine.getState().values.quantity = 3
engine.eval()

// Then dispatch the change event and apply the operations it returns.
const operations = engine.trigger("change", "quantity")

Votre application doit appliquer les opérations renvoyées et décider quand un champ obligatoire vide bloque la soumission.