> ## Documentation Index
> Fetch the complete documentation index at: https://www.chapterjs.org/llms.txt
> Use this file to discover all available pages before exploring further.

# modal()

> Tout ce que déclare un fichier de formulaire, chaque sorte de champ, et ce que reçoit la fonction run pour chacun

`modal()` déclare un formulaire, depuis n’importe quel fichier de `src/` ; le nom de son export est son identifiant. Elle prend un objet, `ModalConfig`, et type `fields` dans `run` d’après lui.

```ts src/components/feedback.ts theme={"theme":{"light":"github-light","dark":"vesper"}}
import { modal } from 'chapterjs';

export default modal({
  title: 'Avis',
  fields: {
    text: { type: 'text', label: 'Qu’en pensez-vous ?', style: 'paragraph' },
  },
  async run({ interaction, fields }) {
    await interaction.reply({ content: `Merci ! Vous avez écrit : ${fields.text}`, ephemeral: true });
  },
});
```

> [!NOTE]
>
> Comment écrire un formulaire, l’ouvrir et lire ce qui a été rempli est dans le [guide](https://www.chapterjs.org/fr/components/modals.md). Cette page liste ce qui existe. L’endroit (`where`, `PlaceOf`...) est sur la [page de button()](https://www.chapterjs.org/fr/reference/button.md#l’endroit).

## modal()

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
modal<Fields extends ModalFields, Data extends DataShape = {}, Where extends ComponentWhere = 'guild'>(config: ModalConfig<Fields, Data, Where>): ModalDeclaration<Fields, Data>
```

Déclare un formulaire. Exportez le résultat depuis n’importe quel fichier de `src/` : le nom de l’export est ce qui distingue le formulaire, donc vous n’écrivez jamais d’identifiant.

### ModalDeclaration

Ce que renvoie `modal()` : une déclaration que le framework trouve dans les exports d’un fichier. Importez-le là où quelqu’un utilise une commande ou un composant, et ouvrez-le : `interaction.showModal(report({ userId }))`, ou `interaction.showModal(feedback)` pour un formulaire sans données.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ModalDeclaration<Fields extends ModalFields = ModalFields, Data extends DataShape = {}> = { readonly config: unknown } &
  ({} extends Data
    ? ((options?: ModalInstanceOptions<Fields>) => ModalComponent) & ModalComponent
    : {} extends DataInputOf<Data>
      ? ((data?: DataInputOf<Data>, options?: ModalInstanceOptions<Fields>) => ModalComponent) & ModalComponent
      : (data: DataInputOf<Data>, options?: ModalInstanceOptions<Fields>) => ModalComponent)
```

**config** `unknown`

Ce que le fichier a donné à `modal()`, pas encore vérifié.

### ModalInstanceOptions

Ce avec quoi un formulaire est ouvert : ses données, et ce que contiennent certains champs.

**values** `ModalPrefill\<Fields\>`

Ce que contiennent certains champs quand le formulaire s’ouvre.

### ModalPrefill

Ce qu’un formulaire peut contenir quand il s’ouvre : une valeur pour certains de ses champs. Un `string` pour un `text`, une liste de valeurs pour un `select` ou des `checkboxes`, une valeur pour un `radio`, un `boolean` pour une `checkbox`. Les autres sortes de champs ne peuvent pas être pré-remplies.

## ModalConfig

Ce qu’un fichier de formulaire donne à `modal()`.

**title** `DynamicText` *required*

Le titre du formulaire (45 caractères au plus) : écrit tel quel, ou une fonction de `t` et des données, lancée à l’ouverture du formulaire. Voir [DynamicText](https://www.chapterjs.org/fr/reference/messages.md#dynamictext).

**fields** `ModalFields` *required*

Les champs, par nom (1 à 5). `run` les reçoit sous les mêmes noms.

**run** `(context: ModalContext\<Fields, Data, Where\>) =\> unknown` *required*

Ce qu’il faut faire quand quelqu’un envoie le formulaire.

**data** `DataShape`

Ce que le formulaire transporte depuis le code qui l’ouvre jusqu’au code qui tourne à l’envoi : un nom et une sorte pour chaque valeur. Donné à l’ouverture du formulaire, reçu typé dans `run`.

**where** `ComponentWhere`

D’où le formulaire peut être envoyé : `'guild'` (serveurs, par défaut), `'dm'` (messages privés avec le bot) ou `'both'`. Ce que reçoit `run` suit.

**ephemeral** `boolean`

Rendre les réponses du formulaire visibles seulement par qui l’a envoyé. Quand un composant d’un message que seule la personne voit l’a ouvert, elles le sont déjà.

[Documentation de Discord](https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-response-object-modal)

## Les champs

### ModalFields

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ModalFields = Readonly<Record<string, ModalField>>
```

Les champs d’un formulaire, par nom (5 au plus). Un nom est la façon dont votre code lit le champ (`fields.reason`) : lettres, chiffres et `_`.

### ModalField

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type ModalField = TextField | SelectField | EntityField | FilesField | RadioField | CheckboxesField | CheckboxField | NoteField
```

Un champ d’un formulaire. Chaque champ sauf une note a :

**label** `DynamicText` *required*

Le nom du champ, au-dessus de lui (45 caractères au plus) : écrit tel quel, ou une fonction de `t` et des données, lancée à l’ouverture du formulaire.

**description** `DynamicText`

Un texte d’aide sous l’étiquette (100 caractères au plus) : un texte, ou une fonction de `t` et des données.

[Documentation de Discord](https://docs.discord.com/developers/components/reference#label)

### TextField

Un texte que la personne tape.

**type** `'text'` *required*

La sorte de champ : un texte.

**style** `'short' | 'paragraph'`

Une ligne (`'short'`, par défaut) ou plusieurs (`'paragraph'`).

**placeholder** `DynamicText`

Le texte affiché tant que le champ est vide (100 caractères au plus) : un texte, ou une fonction de `t` et des données.

**required** `boolean`

Si la personne doit le remplir. `true` par défaut.

**minLength** `number`

Le texte le plus court accepté, en caractères (0 à 4000).

**maxLength** `number`

Le texte le plus long accepté, en caractères (1 à 4000).

**value** `string`

Ce que contient le champ quand le formulaire s’ouvre (4000 caractères au plus).

[Documentation de Discord](https://docs.discord.com/developers/components/reference#text-input)

### SelectField

Un menu de textes que vous déclarez.

**type** `'select'` *required*

La sorte de champ : un menu de textes.

**options** `SelectOptions` *required*

Les options (25 au plus), écrites comme les options d’un [menu déroulant](https://www.chapterjs.org/fr/reference/select.md#selectoptions).

**placeholder** `DynamicText`

Le texte affiché quand rien n’est choisi (150 caractères au plus) : un texte, ou une fonction de `t` et des données.

**min** `number`

Combien d’options doivent être choisies au moins (0 à 25). 1 par défaut.

**max** `number`

Combien d’options peuvent être choisies au plus (1 à 25). 1 par défaut.

**required** `boolean`

Si quelque chose doit être choisi. `true` par défaut.

### EntityField

Un menu d’utilisateurs, de rôles, d’utilisateurs et rôles, ou de salons du serveur.

**type** `'user' | 'role' | 'mentionable' | 'channel'` *required*

La sorte de champ : ce que liste Discord.

**placeholder** `DynamicText`

Le texte affiché quand rien n’est choisi (150 caractères au plus) : un texte, ou une fonction de `t` et des données.

**min** `number`

Combien d’éléments doivent être choisis au moins (0 à 25). 1 par défaut.

**max** `number`

Combien d’éléments peuvent être choisis au plus (1 à 25). 1 par défaut.

**required** `boolean`

Si quelque chose doit être choisi. `true` par défaut.

**channelTypes** `readonly ChannelType[]`

Pour un menu de salons : les sortes de salons listées. Toutes par défaut.

### FilesField

Des fichiers que la personne téléverse.

**type** `'files'` *required*

La sorte de champ : des fichiers à téléverser.

**min** `number`

Combien de fichiers doivent être téléversés au moins (0 à 10). 1 par défaut.

**max** `number`

Combien de fichiers peuvent être téléversés au plus (1 à 10). 1 par défaut.

**required** `boolean`

Si des fichiers doivent être téléversés. `true` par défaut.

**fileTypes** `readonly string[]`

Les sortes de fichiers acceptées : `'image'`, `'video'`, `'audio'`, ou des extensions comme `'.pdf'` (10 au plus).

[Documentation de Discord](https://docs.discord.com/developers/components/reference#file-upload)

### RadioField

Un choix parmi quelques-uns, affiché sous forme de boutons radio.

**type** `'radio'` *required*

La sorte de champ : un choix parmi 2 à 10.

**options** `SelectOptions` *required*

Les choix (2 à 10), écrits comme les options d’un menu déroulant.

**required** `boolean`

Si un choix doit être fait. `true` par défaut.

[Documentation de Discord](https://docs.discord.com/developers/components/reference#radio-group)

### CheckboxesField

Plusieurs choix parmi quelques-uns, affichés sous forme de cases à cocher.

**type** `'checkboxes'` *required*

La sorte de champ : plusieurs choix parmi 1 à 10.

**options** `SelectOptions` *required*

Les choix (1 à 10), écrits comme les options d’un menu déroulant.

**min** `number`

Combien doivent être cochées au moins (0 à 10). 1 par défaut.

**max** `number`

Combien peuvent être cochées au plus (1 à 10). Toutes par défaut.

**required** `boolean`

Si quelque chose doit être coché. `true` par défaut.

[Documentation de Discord](https://docs.discord.com/developers/components/reference#checkbox-group)

### CheckboxField

Une case à cocher : oui ou non.

**type** `'checkbox'` *required*

La sorte de champ : une case à cocher.

**default** `boolean`

Si elle est cochée quand le formulaire s’ouvre.

[Documentation de Discord](https://docs.discord.com/developers/components/reference#checkbox)

### NoteField

Un texte affiché dans le formulaire, que personne ne remplit.

**type** `'note'` *required*

La sorte de champ : un texte à lire.

**content** `DynamicText` *required*

Le texte, avec du Markdown : écrit tel quel, ou une fonction de `t` et des données.

[Documentation de Discord](https://docs.discord.com/developers/components/reference#text-display)

## Ce que reçoit run

### ModalContext

Ce que reçoit `run` quand le formulaire est envoyé : l’endroit tel que le donne [PlaceOf](https://www.chapterjs.org/fr/reference/button.md#placeof) avec une [ModalInteraction](https://www.chapterjs.org/fr/reference/interaction.md#modalinteraction), et :

**user** `User` *required*

Qui a envoyé le formulaire.

**fields** `FieldValuesOf\<Fields\>` *required*

Ce que la personne a rempli.

**data** `DataValuesOf\<Data\>` *required*

Ce que transporte le formulaire, tel que déclaré dans `data`.

**message** `Message | null` *required*

Le message dont le bouton ou le menu a ouvert le formulaire ; `null` quand c’est une commande.

### FieldValuesOf

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
type FieldValuesOf<Fields extends ModalFields> = { [Name in keyof Fields]: FieldValue<Fields[Name]> }
```

Ce que la personne a rempli, typé champ par champ. Les notes n’y sont pas.

### FieldValue

Ce que reçoit `run` pour un champ, d’après sa déclaration :

| Champ | `FieldValue` |
| - | - |
| `TextField` | `string`, ou `string \| undefined` avec `required: false` |
| `SelectField` | `OptionValue<Options>[]` |
| `EntityField` | `User[]`, `Role[]`, `(User \| Role)[]` ou `Channel[]` |
| `FilesField` | [`Attachment`](https://www.chapterjs.org/fr/reference/data#attachment)`[]` |
| `RadioField` | `OptionValue<Options>`, ou `\| undefined` avec `required: false` |
| `CheckboxesField` | `OptionValue<Options>[]` |
| `CheckboxField` | `boolean` |

[Documentation de Discord](https://docs.discord.com/developers/interactions/receiving-and-responding#interaction-object-modal-submit-data-structure)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.