FormBuilder

FormBuilder est le composant d’édition. Il affiche le catalogue, le canvas, les propriétés du champ sélectionné, l’aperçu et les actions d’import/export.

Usage de base

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

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

<template>
  <ClientOnly>
    <FormBuilder
      builder-id="contact"
      v-model:schema="schema"
      v-model:values="values"
    />
  </ClientOnly>
</template>

ClientOnly est recommandé dans Nuxt pour éviter de rendre l’éditeur visuel pendant le SSR.

Sauvegarder

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

type SavePayload = {
  builderId: string
  schema: FormKitSchemaDefinition[]
  values: Record<string, unknown>
  settings: Record<string, unknown>
}

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

async function saveForm(payload: SavePayload) {
  await $fetch('/api/forms/contact', {
    method: 'PUT',
    body: payload,
  })
}
</script>

<template>
  <ClientOnly>
    <FormBuilder
      builder-id="contact"
      v-model:schema="schema"
      v-model:values="values"
      autosave
      @save="saveForm"
    />
  </ClientOnly>
</template>

Le payload @save contient les données nécessaires pour rejouer le formulaire avec FormViewer.

Panneaux responsives

Le builder calcule les panneaux à partir de sa largeur réelle. Il peut donc être placé dans une page pleine largeur, une carte, un onglet ou un panneau redimensionnable.

Mode	Comportement
default	Auto-fit. Les panneaux deviennent overlay quand l’espace manque.
desktop	Les panneaux restent persistants.
mobile	Un panneau overlay à la fois.

<FormBuilder
  builder-id="embedded-contact"
  drawer-behavior="default"
  height="720px"
/>

Sélection et glisser-déposer

Le canvas utilise une seule session d’interaction pour le clic, la sélection, le drag-and-drop et le drop. Cela évite les doubles clics fantômes après déplacement et garde la sélection cohérente entre catalogue, canvas et arborescence.

Les attributs data-qform-interaction-phase, data-qform-selected-field et data-qform-drag-source sont réservés au diagnostic et aux tests.

API par référence

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

type FormBuilderPublicApi = {
  save: () => {
    builderId: string
    schema: FormKitSchemaDefinition[]
    values: Record<string, unknown>
    settings: Record<string, unknown>
  }
  reset: () => void
  exportSchema: () => FormKitSchemaDefinition[]
  importSchema: (schema: FormKitSchemaDefinition[]) => void
}

const builderRef = ref<FormBuilderPublicApi | null>(null)

function downloadSchema() {
  const schema = builderRef.value?.exportSchema() ?? []
  const blob = new Blob([JSON.stringify(schema, null, 2)], { type: 'application/json' })
  const url = URL.createObjectURL(blob)
  const anchor = document.createElement('a')
  anchor.href = url
  anchor.download = 'contact.schema.json'
  anchor.click()
  URL.revokeObjectURL(url)
}
</script>

<template>
  <QBtn label="Exporter" color="primary" @click="downloadSchema" />
  <FormBuilder ref="builderRef" builder-id="contact" />
</template>

Options fréquentes

Option	Description
builder-id	Identifiant stable et obligatoire en pratique.
v-model:schema	Schéma FormKit/Quasar produit par le builder.
v-model:values	Valeurs de prévisualisation ou valeurs initiales.
v-model:preview-mode	editing ou previewing.
autosave	Active la sauvegarde locale de sécurité.
storage-key	Clé d’autosave explicite.
locale	fr ou en.
catalog	Catalogue personnalisé.
config-panels	Panneaux de configuration personnalisés.

Consultez Props, événements et API pour le contrat complet.