Champs calculés
Un champ calculé garde une valeur à jour sans qu’aucun utilisateur ne l’écrive. Vous déclarez le champ, vous nommez une fonction, et vous listez les entrées qui déclenchent une réexécution. Facet exécute la fonction à la création, la relance à chaque changement d’une entrée listée, et stocke le résultat dans le document.
Quand l’utiliser
Section intitulée « Quand l’utiliser »Ajoutez un champ calculé pour une valeur que les utilisateurs devraient sinon tenir à jour à la main, et se tromperaientà : un total sur des lignes de commande, une ancienneté en jours, un numéro composé de plusieurs parties. Un champ calculé ne vient jamais de la saisie utilisateur. Facet refuse toute valeur fournie pour lui.
Avant de commencer
Section intitulée « Avant de commencer »- Trois éléments. Un champ calculé porte le type
data, un nom danscompute, et une listecompute_when. - Une fonction dans le script. La fonction doit exister dans le script du doctype. Facet le vérifie quand vous enregistrez le doctype.
- Lecture seule par conception. Le calcul peut lire des documents, mais jamais en écrire. Pour modifier d’autres documents, utilisez une action ou un hook de domaine.
1. Déclarer le champ
Section intitulée « 1. Déclarer le champ »"total": { "type": "data", "compute": "total", "compute_when": ["qty", "unit_price"]}La valeur de compute nomme la fonction exportée. Facet appelle ainsi compute_total. Chaque entrée de compute_when est soit un champ du doctype, soit le nom d’une relation enfant. Facet exécute tous les champs calculés à la création. À la mise à jour, seuls ceux dont les déclencheurs recoupent les champs modifiés sont relancés.
2. Écrire la fonction
Section intitulée « 2. Écrire la fonction »Renvoyez la valeur. La fonction suit la structure de module standard, comme dans tout script de doctype.
local export = {}
function export.compute_total(ctx) return (ctx.root.qty or 0) * (ctx.root.unit_price or 0)end
return exportRenvoyer nil vide le champ. Utilisez cela pour une valeur conditionnelle, par exemple une ancienneté qui reste vide tant que la date d’embauche n’existe pas.
3. Calculer à partir des enfants
Section intitulée « 3. Calculer à partir des enfants »Quand compute_when nomme une relation enfant, Facet vous fournit les lignes enfants à jour dans ctx.children, et relance le champ du parent dès qu’un enfant de cette relation change.
local export = {}
function export.compute_order_total(ctx) local total = 0 for _, line in ipairs((ctx.children or {}).lines or {}) do total = total + (line.qty or 0) * (line.price or 0) end return totalend
return exportLe champ déclare compute_when: ["lines"], où lines est l’entrée children du doctype.
La définition ci-dessous déclare deux champs d’entrée et le total calculé.
{ "domain": "projects", "doctype": "WorkPackage", "aggregate_root": true, "schema_version": 1, "fields": { "qty": { "type": "integer", "min": 0 }, "unit_price": { "type": "integer", "min": 0 }, "total": { "type": "data", "compute": "total", "compute_when": ["qty", "unit_price"] } }}Une création avec {"qty": 3, "unit_price": 250} stocke total: 750. Un passage de qty à 4 relance la fonction dans la même écriture et stocke total: 1000. Quand le déclencheur est une relation enfant, la réexécution écrit la valeur du parent comme une entrée d’historique distincte.
Dépannage
Section intitulée « Dépannage »Le champ reste vide
Section intitulée « Le champ reste vide »Soit la fonction a renvoyé nil, soit aucun déclencheur n’a été activé. Vérifiez que chaque entrée de compute_when est un nom de champ ou une relation enfant du même doctype. Facet refuse la définition dans le cas contraire.
La valeur reste obsolète après un changement d’enfant
Section intitulée « La valeur reste obsolète après un changement d’enfant »La liste compute_when doit nommer la relation enfant, pas un champ de l’enfant. Avec ["lines"], chaque changement sous lines relance le champ du parent.
L’écriture répond 422 avec Computed fields failed
Section intitulée « L’écriture répond 422 avec Computed fields failed »La fonction a levé une erreur. Lisez le message, corrigez la fonction, et enregistrez le doctype. Un échec déclenche un retour arrière de toute l’écritureà : aucune valeur obsolète n’est stockée.
Un utilisateur a tenté de remplir le champ
Section intitulée « Un utilisateur a tenté de remplir le champ »Par conception, les champs calculés refusent la saisie utilisateur. Retirez le champ du formulaire, ou faites-en un champ normal sans calcul.
Voir aussi
Section intitulée « Voir aussi »- API Lua (référence) — ce qu’une fonction de calcul peut appeler, et ses limites.
- Le journal des mutations — comment une réexécution atterrit dans l’historique.
- Noms d’affichage et texte de recherche — dériver noms et texte de recherche avec des modèles Jinja2.