Utiliser FormBuilder

FormBuilder est le composant public d’édition visuelle.

Il encapsule :

• la toolbar ;
• le panneau des composants ;
• le panneau de propriétés ;
• le canevas ;
• le mode aperçu ;
• le store Pinia isolé par instance ;
• l’autosave ;
• les événements métier.

Exemple minimal

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

type FormBuilderSchema = FormKitSchemaDefinition[]
type FormBuilderValues = Record<string, unknown>

const schema = ref<FormBuilderSchema>([])
const values = ref<FormBuilderValues>({})
</script>

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

Exemple avec sauvegarde

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

type FormBuilderSchema = FormKitSchemaDefinition[]
type FormBuilderValues = Record<string, unknown>

type FormBuilderSavePayload = {
  builderId: string
  schema: FormBuilderSchema
  values: FormBuilderValues
  settings: Record<string, unknown>
}

const schema = ref<FormBuilderSchema>([])
const values = ref<FormBuilderValues>({})
const previewMode = ref<'editing' | 'previewing'>('editing')

function saveForm(payload: FormBuilderSavePayload) {
  console.log('Builder', payload.builderId)
  console.log('Schema', payload.schema)
  console.log('Values', payload.values)
  console.log('Settings', payload.settings)
}
</script>

<template>
  <FormBuilder
    builder-id="contact-form-builder"
    v-model:schema="schema"
    v-model:values="values"
    v-model:preview-mode="previewMode"
    title="Formulaire de contact"
    subtitle="Construisez le formulaire affiché aux utilisateurs"
    autosave
    storage-key="forms:contact:builder-state"
    @save="saveForm"
  />
</template>

Utiliser l’API publique avec ref

FormBuilder expose plusieurs méthodes utiles pour une page admin.

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

type FormBuilderSchema = FormKitSchemaDefinition[]
type FormBuilderValues = Record<string, unknown>

type FormBuilderPublicApi = {
  getBuilderId: () => string
  save: () => {
    builderId: string
    schema: FormBuilderSchema
    values: FormBuilderValues
    settings: Record<string, unknown>
  }
  reset: () => void
  setSchema: (schema: FormBuilderSchema) => void
  getSchema: () => FormBuilderSchema
  setValues: (values: FormBuilderValues) => void
  getValues: () => FormBuilderValues
  setSettings: (settings: Record<string, unknown>) => void
  getSettings: () => Record<string, unknown>
  importSchema: (schema: FormBuilderSchema) => void
  exportSchema: () => FormBuilderSchema
}

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

function exportCurrentSchema() {
  const schema = builderRef.value?.exportSchema() || []
  console.log('Schéma exporté', schema)
}

function clearBuilder() {
  builderRef.value?.reset()
}
</script>

<template>
  <div class="column q-gutter-md">
    <div class="row q-gutter-sm">
      <QBtn label="Exporter" color="primary" @click="exportCurrentSchema" />
      <QBtn label="Réinitialiser" color="negative" flat @click="clearBuilder" />
    </div>

    <FormBuilder
      ref="builderRef"
      builder-id="builder-with-public-api"
      height="calc(100vh - 96px)"
    />
  </div>
</template>

Personnaliser les labels

<template>
  <FormBuilder
    builder-id="custom-labels"
    :labels="{
      save: 'Sauvegarder le formulaire',
      reset: 'Réinitialiser',
      preview: 'Prévisualiser',
      edit: 'Éditer'
    }"
  />
</template>

Slots de toolbar

FormBuilder expose deux slots de toolbar :

• toolbar-before ;
• toolbar-after.

Ils reçoivent schema, values, settings, builderId, et pour toolbar-after, les méthodes save et reset.

<template>
  <FormBuilder builder-id="toolbar-demo">
    <template #toolbar-after="{ builderId, save }">
      <QBtn
        dense
        flat
        icon="cloud_upload"
        label="Publier"
        @click="save()"
      />
      <QBadge outline color="primary">
        {{ builderId }}
      </QBadge>
    </template>
  </FormBuilder>
</template>

Bonne pratique

Garde builder-id stable. Ne le calcule pas à partir d’une donnée qui change pendant le cycle de vie du composant.

À éviter :

<FormBuilder :builder-id="`form-${Date.now()}`" />

À privilégier :

<FormBuilder :builder-id="`form-${formId}`" />