FormLayout — moteur de rendu de formulaires

FormLayout est un composant Vue du paquet @framework/ui (dossier ui/ de Dodock). Il affiche un formulaire à partir d'un schéma : onglets, puis sections, puis colonnes, puis champs. Le schéma vient des métadonnées d'un DocType ou de votre code.

      
flowchart LR
    A[Champs du DocType] --> B[buildLayoutFromMeta]
    C[Schéma écrit à la main] --> D[FormLayout]
    B --> D
    E[Document v-model:doc] --> D
    D --> F[Formulaire affiché]

    

Importer le composant

La racine @framework/ui exporte seulement FormLayout et ses types. Les fonctions de construction sont dans le sous-chemin @framework/ui/FormLayout :

import { FormLayout, buildLayoutFromMeta, fieldsToLayout } from "@framework/ui/FormLayout";

Dans la configuration Vite de votre application, ajoutez le plugin de @framework/ui/vite. Il force une seule copie de vue, vue-router, frappe-ui, reka-ui et dompurify :

// vite.config.js
import frameworkUI from "@framework/ui/vite";

export default defineConfig({
    plugins: [vue(), frameworkUI()],
});

Passez frameworkUI({ dedupe: ["mon-paquet"] }) pour ajouter d'autres paquets à la liste.

Propriétés et modèles

FormLayout n'émet pas d'événement de modification. Pour réagir à toute modification, surveillez le document avec watch(doc, …). Pour réagir à un champ, utilisez l'overlay ui.on (voir plus bas).

Construire le schéma depuis un DocType

buildLayoutFromMeta(fields, options) découpe la liste des champs d'un DocType sur les sauts d'onglet, de section et de colonne.

<script setup>
import { ref } from "vue";
import { createResource } from "frappe-ui";
import { FormLayout, buildLayoutFromMeta } from "@framework/ui/FormLayout";

const doc = ref({ doctype: "ToDo", status: "Open", priority: "Medium", description: "" });
const layout = ref([]);

createResource({
    url: "frappe.desk.form.load.getdoctype",
    params: { doctype: "ToDo" },
    auto: true,
    onSuccess(data) {
        const meta = data.docs.find((d) => d.name === "ToDo");
        layout.value = buildLayoutFromMeta(meta.fields);
    },
});
</script>

<template>
    <FormLayout :layout="layout" v-model:doc="doc" />
</template>

Les champs statiquement masqués restent dans le schéma, pour qu'une surcharge puisse les cibler. Ils ne sont pas affichés.

Écrire un schéma à la main

import type { FormLayoutSchema } from "@framework/ui/FormLayout";

const layout: FormLayoutSchema = [
    {
        name: "details",
        label: "Détails",
        sections: [
            {
                name: "principal",
                label: "Commande",
                columns: [
                    { fields: [{ fieldname: "customer", fieldtype: "Link", options: "Customer", label: "Client", reqd: true }] },
                    { fields: [{ fieldname: "delivery_date", fieldtype: "Date", label: "Date de livraison" }] },
                ],
            },
        ],
    },
];

Un onglet sans libellé masque la barre d'onglets. Pour une liste plate de champs, fieldsToLayout(fields) crée un onglet, une section et une colonne sans libellé.

Clés du schéma

Pour placer un composant Vue entre deux sections ou dans une colonne, voir Insérer un composant personnalisé dans un formulaire FormLayout.

Conditions d'affichage

FormLayout évalue depends_on, mandatory_depends_on et read_only_depends_on à chaque modification du document. Le résultat règle hidden, reqd et readOnly.

{ fieldname: "discount_amount", fieldtype: "Currency", label: "Remise", depends_on: "eval:doc.apply_discount == 1" }

Pour évaluer une condition dans votre code : evaluateDependsOn(expression, doc, parent). Pour obtenir le schéma résolu : resolveLayout(layout, doc, parent).

Surcharger un champ ou y attacher un comportement

Un champ du schéma accepte deux clés propres à l'application :

const layout = buildLayoutFromMeta(meta.fields, {
    decorate(field) {
        if (field.fieldname === "customer") {
            return { on: { change: (value) => chargerConditions(value) } };
        }
    },
});

Un champ émet change quand la saisie est validée : à la sortie du champ pour une saisie, au choix pour un sélecteur. Un champ Button émet click. Dans une cellule de tableau, la ligne est passée en dernier argument : on.click(event, row).

Types de champs

Champ Color

Un champ Color affiche une pastille à côté d'une zone de saisie hexadécimale. Le texte d'invitation par défaut est « Choisissez une couleur » ; la clé placeholder du champ le remplace, et il reste vide en lecture seule. La pastille est un bouton, nommé « Choisir une couleur » pour les lecteurs d'écran, qui ouvre un panneau avec les 13 pastilles du desk classique et un bouton « + » (« Couleur personnalisée ») qui ouvre la boîte de dialogue de couleur du navigateur.

La valeur écrite est toujours au format #rrggbb en minuscules. Une valeur déjà enregistrée avec des majuscules reste telle quelle tant que l'utilisateur ne choisit pas une autre couleur.

La zone de saisie précède la pastille dans le DOM : la touche Tab, l'autofocus d'une boîte de dialogue et les flèches de la grille atteignent d'abord la zone hexadécimale. En lecture seule, le champ montre la pastille et la valeur, sans panneau. Dans une cellule de grille, la pastille garde sa taille de 14 px.

Exemple fictif : un champ personnalisé couleur_marque de type Color dans un schéma écrit à la main.

{ fieldname: "couleur_marque", fieldtype: "Color", label: "Couleur de la marque" }

Un utilisateur qui saisit 1F8CAD puis quitte le champ obtient #1f8cad dans doc.couleur_marque.

Ajouter ou remplacer un type de champ

import { registerFieldType } from "@framework/ui/FormLayout";
import ChampSiret from "./ChampSiret.vue";

registerFieldType("Data", ChampSiret);                    // pour tout le processus
registerFieldType("Data", ChampSiret, { global: false }); // jusqu'au démontage du composant

Avec { global: false }, appelez la fonction dans setup. L'ancien composant revient au démontage. Votre composant reçoit field, modelValue, row et error. Il émet update:modelValue à chaque frappe et change à la validation.

Formats de nombre et de devise

Les champs numériques lisent les réglages du site dans window.sysdefaults, comme le desk. Sans desk, ou pour forcer une valeur, appelez setFormatDefaults :

import { setFormatDefaults } from "@framework/ui/FormLayout";

setFormatDefaults({ number_format: "#.###,##", currency: "EUR", currency_precision: 2 });

Clés acceptées : number_format, currency, currency_precision, float_precision, rounding_method, date_format, time_format. La précision d'un champ (precision) passe avant ces réglages. Les fonctions formatNumber, formatCurrency, formatField et flt sont aussi exportées.