Comprendre le schéma et les valeurs

QForm Builder manipule deux données principales :

schema = structure du formulaire
values = données saisies par l’utilisateur

Schéma

Le schéma est un tableau compatible avec FormKitSchemaDefinition[].

Exemple :

import type { FormKitSchemaDefinition } from '@formkit/core'

const schema: FormKitSchemaDefinition[] = [
  {
    $formkit: 'q-input',
    name: 'lastname',
    label: 'Nom',
    inputType: 'text',
    validation: 'required',
  },
  {
    $formkit: 'q-select',
    name: 'service',
    label: 'Service',
    options: [
      { label: 'DSI', value: 'dsi' },
      { label: 'RH', value: 'rh' },
    ],
  },
]

Valeurs

Les valeurs sont un objet simple :

const values = {
  lastname: 'Durand',
  service: 'dsi',
}

Le lien entre les deux se fait par la propriété name de chaque champ.

Exemple builder + état contrôlé

<script setup lang="ts">
import type { FormKitSchemaDefinition } from '@formkit/core'

const schema = ref<FormKitSchemaDefinition[]>([])
const values = ref<Record<string, unknown>>({})

watch(schema, (nextSchema) => {
  console.log('Schéma modifié', nextSchema)
}, { deep: true })

watch(values, (nextValues) => {
  console.log('Valeurs modifiées', nextValues)
}, { deep: true })
</script>

<template>
  <FormBuilder
    builder-id="controlled-form"
    v-model:schema="schema"
    v-model:values="values"
  />
</template>

Sérialisation

Le builder nettoie les données avant export afin d’éviter les erreurs courantes liées aux objets non sérialisables :

Vue refs
fonctions
symboles
objets DOM
Events
cycles d’objets

Cela permet d’envoyer le payload vers une API ou de le sauvegarder en JSON.

Format conseillé pour le stockage

import type { FormKitSchemaDefinition } from '@formkit/core'

export type StoredDynamicForm = {
  id: string
  name: string
  slug: string
  schema: FormKitSchemaDefinition[]
  settings: Record<string, unknown>
  status: 'draft' | 'published' | 'archived'
  createdAt: string
  updatedAt: string
}

Bonne pratique

Versionne le format des schémas dès le départ :

export type StoredDynamicForm = {
  schemaVersion: 1
  schema: FormKitSchemaDefinition[]
  // autres propriétés
}

Cela facilitera les migrations si les composants Quasar/FormKit évoluent.