Référence FormBuilder et FormViewer

FormBuilder

Props

Prop	Type	Défaut	Description
builder-id	string	default	Identifiant stable de l’instance. Isole le store, l’historique et l’autosave.
schema	FormKitSchemaDefinition[]	[]	Schéma contrôlé via v-model:schema.
values	Record<string, unknown>	{}	Valeurs contrôlées via v-model:values.
settings	Partial<FormBuilderSettings>	interne	Paramètres du builder.
readonly	boolean	false	Force le mode lecture seule.
disabled	boolean	false	Désactive les actions utilisateur.
autosave	boolean	false	Active la sauvegarde locale automatique.
storage-key	string	calculée	Clé localStorage utilisée par l’autosave.
title	string	Constructeur de formulaires	Titre affiché dans la toolbar.
subtitle	string	texte interne	Sous-titre affiché dans la toolbar.
height	string	100vh	Hauteur du shell du builder.
left-drawer-open	boolean	interne	Contrôle le panneau gauche.
right-drawer-open	boolean	interne	Contrôle le panneau droit.
preview-mode	'editing' | 'previewing'	interne	Mode courant.
drawer-behavior	'default' | 'desktop' | 'mobile'	default	default mesure la largeur réelle du builder, ajuste automatiquement les deux panneaux et bascule en overlay lorsque le canvas ne peut plus rester lisible. desktop et mobile restent des forçages explicites.
labels	Partial<FormBuilderLabels>	{}	Surcharges ciblées des libellés historiques de toolbar.
locale	QFormBuilderLocaleCode	fr	Locale UI active. Les locales intégrées sont fr et en.
locales	QFormBuilderLocaleRegistry	{}	Surcharges profondes ou locales supplémentaires fournies par l’application hôte.
catalog	QFormBuilderCatalog	[]	Éléments personnalisés ajoutés ou utilisés en remplacement du catalogue Community.
catalog-mode	'append' | 'replace'	append	Fusionne le catalogue ou le remplace entièrement.
templates	QFormBuilderTemplateRegistry	[]	Modèles personnalisés fusionnés avec le registre Community.
template-mode	'append' | 'replace'	append	Fusionne les modèles personnalisés ou remplace le registre Community.
config-panels	QFormBuilderConfigPanelRegistry	[]	Registre public de panneaux de propriétés fournis par l’application hôte.
validation-rules	QFormBuilderValidationRuleRegistry	[]	Registre runtime des règles métier personnalisées et de leurs messages localisés.
history-open	boolean	false	Contrôle l’ouverture du panneau d’historique.
history-depth	number	50	Nombre maximal d’états conservés, borné entre 2 et 500.
history-shortcuts	boolean	true	Active les raccourcis undo/redo sécurisés.
theme	QFormBuilderThemeInput	Enterprise	Thème contrôlé partagé par le builder et le viewer.
theme-open	boolean	false	Contrôle l’ouverture du Theme Builder.

v-model

<FormBuilder
  v-model:schema="schema"
  v-model:values="values"
  v-model:settings="settings"
  v-model:left-drawer-open="leftDrawerOpen"
  v-model:right-drawer-open="rightDrawerOpen"
  v-model:preview-mode="previewMode"
  v-model:history-open="historyOpen"
  v-model:history-depth="historyDepth"
  v-model:theme="theme"
  v-model:theme-open="themeOpen"
/>

Événements

Événement	Payload	Description
save	{ builderId, schema, values, settings }	Déclenché par le bouton sauvegarder ou save().
reset	aucun	Déclenché après réinitialisation.
cancel	aucun	Réservé pour usage hôte.
submit	values	Déclenché lors de la soumission en preview.
field-add	{ field, index, schema }	Champ ajouté.
field-update	{ field, index, schema }	Champ modifié.
field-remove	{ field, index, schema }	Champ supprimé.
field-copy	{ field, index, schema }	Champ copié.
field-select	{ field, index, schema }	Champ sélectionné.
field-move	{ field, from, to, fromTarget?, toTarget?, schema }	Champ déplacé, y compris entre conteneurs imbriqués.
schema-import	schema	Schéma importé via API publique.
schema-export	schema	Schéma historique exporté via API publique.
document-import	QFormBuilderDocumentImportEvent	Document importé avec source, versions, migrations, avertissements et groupes appliqués.
document-export	QFormBuilderDocumentExportEvent	Document canonique versionné exporté.
template-apply	QFormBuilderTemplateApplyEvent	Modèle appliqué avec mode, schéma, valeurs, réglages et table de renommage.
history-change	QFormBuilderHistoryChangeEvent	Timeline, pointeur ou profondeur modifiés.
history-undo	QFormBuilderHistoryNavigationEvent	Undo appliqué avec succès.
history-redo	QFormBuilderHistoryNavigationEvent	Redo appliqué avec succès.
history-restore	QFormBuilderHistoryNavigationEvent	Restauration explicite appliquée.
error	{ code, message, cause? }	Erreur contrôlée du builder.

API exposée par ref

export type FormBuilderPublicApi = {
  getBuilderId: () => string
  save: () => {
    builderId: string
    schema: FormKitSchemaDefinition[]
    values: Record<string, unknown>
    settings: Record<string, unknown>
  }
  reset: () => void
  setSchema: (schema: FormKitSchemaDefinition[]) => void
  getSchema: () => FormKitSchemaDefinition[]
  setValues: (values: Record<string, unknown>) => void
  getValues: () => Record<string, unknown>
  setSettings: (settings: Record<string, unknown>) => void
  getSettings: () => Record<string, unknown>
  importSchema: (schema: FormKitSchemaDefinition[]) => void
  exportSchema: () => FormKitSchemaDefinition[]
  importDocument: (input: unknown, options?: QFormBuilderDocumentImportOptions) => QFormBuilderMigrationResult | null
  exportDocument: (options?: QFormBuilderDocumentCreateOptions) => QFormBuilderDocument
  getHistory: () => QFormBuilderHistorySnapshot
  undo: () => QFormBuilderHistoryEntry | null
  redo: () => QFormBuilderHistoryEntry | null
  restoreHistoryEntry: (entryId: string) => QFormBuilderHistoryEntry | null
  clearHistory: () => void
  setHistoryDepth: (depth: number) => number
  openHistory: () => void
  closeHistory: () => void
  setTheme: (theme: QFormBuilderThemeInput) => QFormBuilderThemeConfig
  getTheme: () => QFormBuilderThemeConfig
  openTheme: () => void
  closeTheme: () => void
  getTemplates: () => QFormBuilderTemplateRegistry
  applyTemplate: (
    templateKey: string,
    options?: QFormBuilderTemplateApplyOptions,
  ) => QFormBuilderTemplateApplyEvent | null
}

FormViewer

Props

Prop	Type	Défaut	Description
form-fields	FormKitSchemaDefinition[]	requis	Schéma à rendre.
readonly	boolean	false	Bloque les modifications et la soumission.
locale	QFormBuilderLocaleCode	fr	Locale des composants runtime.
locales	QFormBuilderLocaleRegistry	{}	Surcharges profondes ou locales supplémentaires.
validation-rules	QFormBuilderValidationRuleRegistry	[]	Même registre runtime que celui utilisé pour construire le schéma.
theme	QFormBuilderThemeInput	Enterprise	Applique les mêmes design tokens que le builder.

v-model

<FormViewer
  v-model="values"
  :form-fields="schema"
/>

Le modèle correspond aux valeurs du formulaire :

const values = ref<Record<string, unknown>>({})

Événement submit

<FormViewer
  v-model="values"
  :form-fields="schema"
  @submit="handleSubmit"
/>

function handleSubmit(data: Record<string, unknown>) {
  console.log(data)
}

Types publics

Les types sont exportés par le package :

import type {
  FormBuilderPublicApi,
  FormBuilderSavePayload,
  FormBuilderSchema,
  FormBuilderValues,
  QFormBuilderDocument,
  QFormBuilderDocumentImportEvent,
  QFormBuilderMigrationResult,
  QFormBuilderLocale,
  QFormBuilderLocaleCode,
  QFormBuilderLocaleOverrides,
  QFormBuilderLocaleRegistry,
  QFormBuilderCatalog,
  QFormBuilderCatalogMode,
  QFormBuilderElementDefinition,
  QFormBuilderConfigPanelDefinition,
  QFormBuilderConfigPanelProps,
  QFormBuilderConfigPanelRegistry,
  QFormBuilderValidationRuleDefinition,
  QFormBuilderValidationRuleRegistry,
  QFormBuilderValidationMessages,
  QFormBuilderHistoryAction,
  QFormBuilderHistoryEntry,
  QFormBuilderHistorySnapshot,
  QFormBuilderHistoryChangeEvent,
  QFormBuilderHistoryNavigationEvent,
  QFormBuilderThemeConfig,
  QFormBuilderThemePresetKey,
  QFormBuilderTemplateDefinition,
  QFormBuilderTemplateSettings,
  QFormBuilderTemplateRegistry,
  QFormBuilderTemplateApplyMode,
  QFormBuilderTemplateApplyOptions,
  QFormBuilderTemplateApplyEvent,
  QFormBuilderAccessibilityApi,
  QFormBuilderAccessibilityAnnouncementOptions,
} from '@vevedh/qform-builder-layer/types'

Édition des colonnes imbriquées

Les colonnes de q-columns sont des nœuds de configuration internes, pas des composants publics séparés. Leur sélection et leur édition mettent à jour v-model:schema comme toute autre modification du builder. Le contrat de données est exposé par QFormBuilderColumnDefinition.

Validation publique des imports

import {
  parseQFormBuilderSchema,
  sanitizeQFormBuilderSchema,
} from '@vevedh/qform-builder-layer/schema-transfer'

Le sous-chemin schema-transfer fournit le même contrôle de taille, de structure et de contenu actif que l’interface d’import du builder.

Helpers de validation publique

import {
  parseQFormBuilderValidation,
  resolveQFormBuilderValidationRegistry,
  validateQFormBuilderRegex,
} from '@vevedh/qform-builder-layer/validation'

Voir Validation avancée pour le contrat de registre, les regex et les comparaisons entre champs.

Helpers publics d’historique

import {
  appendQFormBuilderHistory,
  createQFormBuilderHistoryState,
  formatQFormBuilderHistoryLabel,
  normalizeQFormBuilderHistoryDepth,
  restoreQFormBuilderHistory,
} from '@vevedh/qform-builder-layer/history'

Voir Historique visible et restauration.

Helpers publics de modèles

import {
  applyQFormBuilderTemplate,
  canAppendQFormBuilderTemplate,
  createCommunityTemplates,
  defineQFormTemplate,
  mergeQFormBuilderTemplates,
} from '@vevedh/qform-builder-layer/templates'

Voir Modèles de formulaires pour les modes replace/append, le renommage des collisions et le registre personnalisé.

Helpers publics de thème

import {
  applyQFormBuilderThemePreset,
  createQFormBuilderTheme,
  mergeQFormBuilderTheme,
  normalizeQFormBuilderTheme,
  qFormBuilderThemeToCssVariables,
} from '@vevedh/qform-builder-layer/theme'

Voir Theme Builder et champ couleur Quasar.

API d’accessibilité imbriquée

Un composant ou panneau personnalisé rendu sous FormBuilder peut utiliser le composable auto-importé :

const accessibility = useFormBuilderAccessibility()

accessibility.announce('Configuration appliquée')
await accessibility.focusField('email')

Le composable est isolé par instance et fournit un repli sans effet hors builder. Voir Accessibilité, clavier et audit axe.