Skip to main content

Syntaxe 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.

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.

YAML
- 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)
    default: 0
  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éDescriptionObligatoireTypeDefaultValeurs valides
typeType d’élément à définir.String
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idIdentificateur 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
attributesEnsemble de paires clé-valeur qui définissent les propriétés de l’élément.Mappage
validationsEnsemble 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.

TypeDescription
markdownTexte au format Markdown affiché dans le formulaire, qui permet de fournir un contexte supplémentaire à l’utilisateur mais qui n’est pas envoyé.
textareaChamp de texte multiligne.
inputChamp de texte d’une seule ligne.
dropdownMenu déroulant.
checkboxesEnsemble 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éDescriptionObligatoireTypeDefaultValeurs valides
valueTexte 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.

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éDescriptionObligatoireTypeDefaultValeurs valides
labelBrève description de l’entrée utilisateur attendue, qui s’affiche également dans le formulaire.String
descriptionDescription de la zone de texte, qui permet de fournir un contexte ou un conseil d’aide, et qui s’affiche dans le formulaire.StringChaîne vide
placeholderEspace réservé semi-opaque qui s’affiche dans la zone de texte quand elle est vide.StringChaîne vide
valueTexte prérempli dans la zone de texte.String
renderSi 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.StringLangages 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éDescriptionObligatoireTypeDefaultValeurs valides
requiredEmpêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics.Booleanfalse

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

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éDescriptionObligatoireTypeDefaultValeurs valides
labelBrève description de l’entrée utilisateur attendue, qui s’affiche également dans le formulaire.String
descriptionDescription du champ, qui permet de fournir un contexte ou un conseil d’aide, et qui s’affiche dans le formulaire.StringChaîne vide
placeholderEspace réservé semi-transparent qui s’affiche dans le champ quand il est vide.StringChaîne vide
valueTexte 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éDescriptionObligatoireTypeDefaultValeurs valides
requiredEmpêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics.Booleanfalse

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

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éDescriptionObligatoireTypeDefaultValeurs valides
labelBrève description de l’entrée utilisateur attendue, qui s’affiche dans le formulaire.String
descriptionDescription du menu déroulant, qui permet de fournir un contexte ou un conseil d’aide supplémentaire, et qui s’affiche dans le formulaire.StringChaîne vide
multipleDétermine si l’utilisateur peut sélectionner plusieurs options.Booléenfalse
optionsTableau d’options proposées à l’utilisateur. Ne peut pas être vide. Tous les choix doivent être distincts.Tableau de chaînes
defaultIndex 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.Entier

Validations pour dropdown

Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.

CléDescriptionObligatoireTypeDefaultValeurs valides
requiredEmpêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics.Booleanfalse

Exemple de dropdown

body:
- type: dropdown
  id: download
  attributes:
    label: How did you download the software?
    options:
      - Built from source
      - Homebrew
      - MacPorts
      - apt-get
    default: 0
  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éDescriptionObligatoireTypeDefaultValeurs valides
labelBrève description de l’entrée utilisateur attendue, qui s’affiche dans le formulaire.String
descriptionDescription de l’ensemble des cases à cocher, qui s’affiche dans le formulaire. Prend en charge la mise en forme en Markdown.StringChaîne vide
optionsTableau 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éDescriptionObligatoireTypeDefaultOptions
labelIdentificateur 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

Validations pour checkboxes

Pour la valeur de la clé validations, vous pouvez définir les clés suivantes.

CléDescriptionObligatoireTypeDefaultValeurs valides
requiredEmpêche l’envoi de formulaire tant que l’élément n’est pas effectué. Uniquement pour les dépôts publics.Booleanfalse

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

Pour aller plus loin