Remarque : Le schéma de formulaire de GitHub est en version bêta, et peut être amené à changer.
À propos du schéma de formulaire de GitHub
Vous pouvez utiliser le schéma de formulaire de GitHub afin de configurer les formulaires pour les fonctionnalités prises en charge. Pour plus d’informations, consultez « Configuration des modèles de problème pour votre dépôt ».
Un formulaire est un ensemble d’éléments permettant de demander une entrée utilisateur. Vous pouvez configurer un formulaire en créant une définition de formulaire YAML, qui est un tableau d’éléments de formulaire. Chaque élément de formulaire est un ensemble de paires clé-valeur qui déterminent le type de l’élément, les propriétés de l’élément ainsi que les contraintes à appliquer à l’élément. Pour certaines clés, la valeur est un autre ensemble de paires clé-valeur.
Par exemple, la définition de formulaire suivante comprend quatre éléments de formulaire : une zone de texte pour indiquer le système d’exploitation de l’utilisateur, un menu déroulant pour choisir la version logicielle exécutée par l’utilisateur, une case à cocher pour accuser réception du code de conduite et un message en Markdown pour remercier l’utilisateur d’avoir rempli le formulaire.
- type: textarea
attributes:
label: Operating System
description: What operating system are you using?
placeholder: "Example: macOS Big Sur"
value: operating system
validations:
required: true
- type: dropdown
attributes:
label: Version
description: What version of our software are you running?
multiple: false
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: checkboxes
attributes:
label: Code of Conduct
description: The Code of Conduct helps create a safe space for everyone. We require
that everyone agrees to it.
options:
- label: I agree to follow this project's [Code of Conduct](link/to/coc)
required: true
- type: markdown
attributes:
value: "Thanks for completing our form!"
- type: textarea
attributes:
label: Operating System
description: What operating system are you using?
placeholder: "Example: macOS Big Sur"
value: operating system
validations:
required: true
- type: dropdown
attributes:
label: Version
description: What version of our software are you running?
multiple: false
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: checkboxes
attributes:
label: Code of Conduct
description: The Code of Conduct helps create a safe space for everyone. We require
that everyone agrees to it.
options:
- label: I agree to follow this project's [Code of Conduct](link/to/coc)
required: true
- type: markdown
attributes:
value: "Thanks for completing our form!"
Keys
Pour chaque élément de formulaire, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
type | Type d’élément à définir. | String |
| ||
id | Identificateur de l’élément, sauf quand type a la valeur markdown. Peut uniquement utiliser des caractères alphanumériques, - et _. Doit être unique dans la définition de formulaire. S’il est fourni, id est l’identificateur canonique du champ dans le préremplissage des paramètres de requête d’URL. | String | |||
attributes | Ensemble de paires clé-valeur qui définissent les propriétés de l’élément. | Mappage | |||
validations | Ensemble de paires clé-valeur qui définissent des contraintes sur l’élément. | Mappage |
Vous pouvez choisir l’un des types d’élément de formulaire suivants. Chaque type a des attributs et des validations uniques.
| Type | Description |
|---|---|
markdown | Texte au format Markdown affiché dans le formulaire, qui permet de fournir un contexte supplémentaire à l’utilisateur mais qui n’est pas envoyé. |
textarea | Champ de texte multiligne. |
input | Champ de texte d’une seule ligne. |
dropdown | Menu déroulant. |
checkboxes | Ensemble de cases à cocher. |
markdown
Vous pouvez utiliser un élément markdown pour afficher du texte au format Markdown dans votre formulaire afin de fournir un contexte supplémentaire à l’utilisateur, mais qui n’est pas envoyé.
Attributs pour markdown
Pour la valeur de la clé attributes, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
value | Texte affiché. La mise en forme en Markdown est prise en charge. | String |
Conseils : Le traitement YAML interprète le symbole du mot-dièse en tant que commentaire. Pour insérer des en-têtes Markdown, placez votre texte entre guillemets.
Pour du texte multiligne, vous pouvez utiliser l’opérateur représenté par la barre verticale.
Exemple de markdown
body:
- type: markdown
attributes:
value: "## Thank you for contributing to our project!"
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report.
body:
- type: markdown
attributes:
value: "## Thank you for contributing to our project!"
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report.
textarea
Vous pouvez utiliser un élément textarea pour ajouter un champ de texte multiligne à votre formulaire. Les contributeurs peuvent également joindre des fichiers dans les champs textarea.
Attributs pour textarea
Pour la valeur de la clé attributes, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
label | Brève description de l’entrée utilisateur attendue, qui s’affiche également dans le formulaire. | String | |||
description | Description de la zone de texte, qui permet de fournir un contexte ou un conseil d’aide, et qui s’affiche dans le formulaire. | String | Chaîne vide | ||
placeholder | Espace réservé semi-opaque qui s’affiche dans la zone de texte quand elle est vide. | String | Chaîne vide | ||
value | Texte prérempli dans la zone de texte. | String | |||
render | Si une valeur est fournie, le texte envoyé est mis en forme dans un bloc de code. Quand cette clé est fournie, la zone de texte ne se développe pas pour les pièces jointes ou la modification en Markdown. | String | Langages connus de GitHub. Pour plus d’informations, consultez le fichier YAML des langages. |
Validations pour textarea
Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
required | Empêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics. | Boolean | false |
Exemple de textarea
body:
- type: textarea
id: repro
attributes:
label: Reproduction steps
description: "How do you trigger this bug? Please walk us through it step by step."
value: |
1.
2.
3.
...
render: bash
validations:
required: true
body:
- type: textarea
id: repro
attributes:
label: Reproduction steps
description: "How do you trigger this bug? Please walk us through it step by step."
value: |
1.
2.
3.
...
render: bash
validations:
required: true
input
Vous pouvez utiliser un élément input pour ajouter un champ de texte d’une seule ligne à votre formulaire.
Attributs pour input
Pour la valeur de la clé attributes, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
label | Brève description de l’entrée utilisateur attendue, qui s’affiche également dans le formulaire. | String | |||
description | Description du champ, qui permet de fournir un contexte ou un conseil d’aide, et qui s’affiche dans le formulaire. | String | Chaîne vide | ||
placeholder | Espace réservé semi-transparent qui s’affiche dans le champ quand il est vide. | String | Chaîne vide | ||
value | Texte prérempli dans le champ. | String |
Validations pour input
Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
required | Empêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics. | Boolean | false |
Exemple de input
body:
- type: input
id: prevalence
attributes:
label: Bug prevalence
description: "How often do you or others encounter this bug?"
placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
validations:
required: true
body:
- type: input
id: prevalence
attributes:
label: Bug prevalence
description: "How often do you or others encounter this bug?"
placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
validations:
required: true
dropdown
Vous pouvez utiliser un élément dropdown pour ajouter un menu déroulant dans votre formulaire.
Attributs pour dropdown
Pour la valeur de la clé attributes, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
label | Brève description de l’entrée utilisateur attendue, qui s’affiche dans le formulaire. | String | |||
description | Description du menu déroulant, qui permet de fournir un contexte ou un conseil d’aide supplémentaire, et qui s’affiche dans le formulaire. | String | Chaîne vide | ||
multiple | Détermine si l’utilisateur peut sélectionner plusieurs options. | Booléen | false | ||
options | Tableau d’options proposées à l’utilisateur. Ne peut pas être vide. Tous les choix doivent être distincts. | Tableau de chaînes | |||
default | Index de l’option présélectionnée dans le tableau options. Lorsqu’une option par défaut est spécifiée, vous ne pouvez pas inclure « None » (aucun) ou « n/a » (sans objet) comme options. | Integer |
Validations pour dropdown
Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
required | Empêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics. | Boolean | false |
Exemple de dropdown
body:
- type: dropdown
id: download
attributes:
label: How did you download the software?
options:
- Built from source
- Homebrew
- MacPorts
- apt-get
validations:
required: true
body:
- type: dropdown
id: download
attributes:
label: How did you download the software?
options:
- Built from source
- Homebrew
- MacPorts
- apt-get
validations:
required: true
checkboxes
Vous pouvez utiliser l’élément checkboxes pour ajouter un ensemble de cases à cocher à votre formulaire.
Attributs pour checkboxes
Pour la valeur de la clé attributes, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
label | Brève description de l’entrée utilisateur attendue, qui s’affiche dans le formulaire. | String | |||
description | Description de l’ensemble des cases à cocher, qui s’affiche dans le formulaire. Prend en charge la mise en forme en Markdown. | String | Chaîne vide | ||
options | Tableau de cases à cocher que l’utilisateur peut sélectionner. Pour la syntaxe, consultez les informations ci-dessous. | Array |
Pour chaque valeur du tableau options, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Options |
|---|---|---|---|---|---|
label | Identificateur de l’option, affiché dans le formulaire. Markdown est pris en charge pour la mise en forme en gras ou en italique du texte, et pour les liens hypertexte. | String | |||
required | Empêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics. | Boolean | false |
Validations pour checkboxes
Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.
| Clé | Description | Obligatoire | Type | Default | Valeurs valides |
|---|---|---|---|---|---|
required | Empêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics. | Boolean | false |
Exemple de checkboxes
body:
- type: checkboxes
id: operating-systems
attributes:
label: Which operating systems have you used?
description: You may select more than one.
options:
- label: macOS
- label: Windows
- label: Linux
body:
- type: checkboxes
id: operating-systems
attributes:
label: Which operating systems have you used?
description: You may select more than one.
options:
- label: macOS
- label: Windows
- label: Linux