# Groupes de champs

Un formulaire de vingt champs rendu en une seule colonne plate oblige le contributeur à lire chaque saisie avant d'en comprendre une seule. Les mêmes champs sous trois intitulés — « À votre sujet », « Votre expérience », « Pourquoi nous » — deviennent quelque chose qu'on parcourt du regard et qu'on remplit section par section.

`fieldGroups` déclare ces intitulés. Chaque entrée associe un libellé aux noms des champs qui lui appartiennent :

```yaml
forms:
  - id: 1
    name: apply
    title: Apply for Senior Engineer
    submitTo: { table: candidates }
    fieldGroups:
      - label: About you
        fields: [first_name, last_name, email]
      - label: Your experience
        fields: [years_of_experience, github_url]
    fields:
      - { kind: table-field, column: first_name, required: true }
      - { kind: table-field, column: last_name, required: true }
      - { kind: table-field, column: email, required: true }
      - { kind: standalone, name: years_of_experience, inputType: number }
      - { kind: standalone, name: github_url, inputType: url }
```

## Propriétés d'un groupe

| Propriété     | Description                                                                                             | Défaut            |
| ------------- | ------------------------------------------------------------------------------------------------------- | ----------------- |
| `label`       | Intitulé de section affiché au-dessus des champs du groupe. Au moins un caractère.                      | Obligatoire.      |
| `fields`      | Noms des champs appartenant à la section, dans l'ordre d'affichage souhaité. Au moins un.               | Obligatoire.      |
| `visibleWhen` | Condition qui régit la section entière. Même forme et mêmes opérateurs que le `visibleWhen` d'un champ. | Toujours visible. |

`fieldGroups` est lui-même optionnel. Omettez-le et le formulaire affiche `fields[]` de haut en bas sans aucun intitulé — le bon choix pour un formulaire assez court pour se passer de balisage. Lorsqu'il est présent, le tableau doit déclarer au moins un groupe.

## L'ordre vient des groupes

Dès lors que `fieldGroups` existe, c'est lui qui pilote la mise en page : les sections s'affichent dans l'ordre du tableau, et chaque champ apparaît à la place que lui donne son groupe. Le regroupement peut donc réorganiser un formulaire sans toucher à `fields[]` — `fields[]` continue de définir _ce que sont_ les champs, les groupes définissent _où_ ils apparaissent.

Un champ que vous n'avez listé nulle part s'affiche quand même. Il retombe tout en bas, après toutes les sections, dans l'ordre source de `fields[]`. Regrouper la moitié d'un formulaire est donc valide : les champs nommés reçoivent leurs intitulés, les autres suivent en bloc non libellé.

## Sections conditionnelles

`visibleWhen` conditionne une section entière — le libellé et tous ses champs — à la valeur d'un autre champ, avec la même primitive de condition que les règles au niveau du champ :

```yaml
fieldGroups:
  - label: Preferences
    fields: [wants_relocation]
  - label: Relocation
    fields: [relocation_country, relocation_date]
    visibleWhen: { field: wants_relocation, operator: eq, value: true }
```

La règle est évaluée côté serveur. Au premier rendu aucune réponse n'existe encore : une section conditionnelle démarre donc masquée et apparaît dès que son déclencheur est renseigné. À la soumission, la règle est réévaluée, cette fois contre les valeurs soumises, et une section dont la règle est fausse est traitée comme si elle n'avait jamais fait partie du formulaire : ses champs obligatoires ne bloquent pas l'envoi.

:::callout
**Une section masquée abandonne ses valeurs, elle ne se contente pas d'ignorer la validation.** Quand le `visibleWhen` d'un groupe est faux au moment de la soumission, chacun de ses champs est retiré de la charge utile avant l'écriture dans la table et dans le registre. Une valeur saisie par le contributeur pendant que la section était ouverte — puis masquée en changeant le déclencheur — n'est pas persistée. Ne placez jamais un champ dont vous avez toujours besoin dans un groupe conditionnel.
:::

## Groupes ou étapes

Les deux découpent un formulaire, et les deux acceptent un `visibleWhen`. La différence tient à ce que le contributeur voit d'un seul coup.

| À utiliser    | Quand                                                                                                                                                   |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fieldGroups` | Tous les champs restent sur une page et un seul défilement ; les intitulés donnent la structure. Exige `layout: single-page` (le défaut).               |
| `steps`       | Les champs sont répartis sur plusieurs écrans, avec navigation précédent/suivant et validation par étape. Exige `layout: multi-step` ou `one-question`. |

## Pages associées

- [Champs de formulaire](/fr/docs/form-fields) — les entrées `fields[]` qu'un groupe désigne par leur nom.
- [Logique conditionnelle](/fr/docs/form-conditional-logic) — le vocabulaire d'opérateurs dans lequel puise `visibleWhen`.
- [Formulaires multi-étapes](/fr/docs/form-multi-step) — `steps[]`, l'alternative multi-écrans aux groupes.
- [Présentation des formulaires](/fr/docs/forms-overview) — la place de `fieldGroups` dans le schéma complet.