Sintaxe para o esquema de formulário do GitHub

Observação: atualmente, o esquema de formulário do GitHub está em versão beta e sujeito a alterações.

Sobre o esquema de formulário de GitHub

Você pode usar o esquema de formulário de GitHub para configurar formulários para funcionalidades compatíveis. Para obter mais informações, confira "Como configurar modelos de problemas para seu repositório".

Um formulário é um conjunto de elementos que solicita a entrada do usuário. Você pode configurar um formulário criando uma definição de formulário YAML, que é uma matriz de elementos de formulário. Cada elemento de formulário é um conjunto de par chave-valor que determina o tipo do elemento, as propriedades do elemento e as restrições que você deseja aplicar ao elemento. Para algumas chaves, o valor é outro conjunto de pares de chave-valor.

Por exemplo, a definição de formulário a seguir inclui quatro elementos de formulário: uma área de texto para fornecer o sistema operacional do usuário, um menu suspenso para escolher a versão de software que o usuário está executando, uma caixa de seleção para reconhecer o Código de Conduta e Markdown que agradece ao usuário por ter preenchido o formulário.

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:
      - label: 1.0.2 (Default)
      - label: 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!"

simétricas

Para cada elemento de formulário, você pode definir as seguintes chaves.

Chave	Descrição	Obrigatório	Tipo	Valores válidos
`type`	O tipo de elemento que você deseja definir.	Obrigatório	String	`checkboxes` `dropdown` `input` `markdown` `textarea`
`id`	O identificador do elemento, exceto quando `type` é definido como `markdown`. Só pode usar caracteres alfanuméricos, `-` e `_`. Deve ser único na definição da forma. Se isso for fornecido, a `id` será o identificador canônico do campo nos preenchimentos prévios de parâmetro de consulta de URL.	Opcional	String
`attributes`	Um conjunto de pares chave-valor que definem as propriedades do elemento.	Obrigatório	Mapeamento
`validations`	Um conjunto de pares chave-valor que define restrições sobre o elemento.	Opcional	Mapeamento

Você pode escolher entre os seguintes tipos de elementos de formulário. Cada tipo tem atributos e validações exclusivos.

Tipo	Descrição
`markdown`	Texto Markdown exibido no formulário para fornecer contexto extra ao usuário, mas que não é enviado.
`textarea`	Um campo de texto linha múltipla.
`input`	Um campo de texto de linha única.
`dropdown`	Um menu suspenso.
`checkboxes`	Um conjunto de caixas de seleção.

`markdown`

Você pode usar um elemento markdown para exibir o Markdown no seu formulário que fornece contexto extra ao usuário, mas que não é enviado.

Atributos

Para o valor da chave attributes, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`value`	O texto que é interpretado. A formatação de Markdown é compatível.	Obrigatório	String

Dicas: o processamento do YAML tratará o símbolo de hash como um comentário. Para inserir cabeçalhos do Markdown, coloque seu texto entre aspas.

Para texto de linhas múltiplas, você pode usar o operador de pipe.

Exemplo

YAML

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`

Você pode usar um elemento textarea para adicionar um campo de texto de várias linhas ao formulário. Os colaboradores também podem anexar arquivos em campos textarea.

Atributos

Para o valor da chave attributes, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`label`	Uma breve descrição da entrada esperada do usuário, que também é exibida no formulário.	Obrigatório	String
`description`	Uma descrição da área de texto para fornecer contexto ou orientação, que é exibida no formulário.	Opcional	String	String vazia
`placeholder`	Um marcador semi-opaco interpretado na área de texto quando vazio.	Opcional	String	String vazia
`value`	Texto pré-preenchido na área de texto.	Opcional	String
`render`	Se um valor for fornecido, o texto enviado será formatado de bloco de código. Quando esta chave é fornecida, a área de texto não será expandida para anexos de arquivos ou edição de markdown.	Opcional	String		Linguagens conhecidas para GitHub. Para obter mais informações, confira o arquivo YAML de linguagens.

Validações

Para o valor da chave validations, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`required`	Impede o envio do formulário até que o elemento seja concluído.	Optional	Boolean	false

Exemplo

YAML

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`

Você pode usar um elemento input para adicionar um campo de texto de linha única ao formulário.

Atributos

Para o valor da chave attributes, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão
`label`	Uma breve descrição da entrada esperada do usuário, que também é exibida no formulário.	Obrigatório	String
`description`	Uma descrição do campo para fornecer contexto ou orientação, que é exibida no formulário.	Opcional	String	String vazia
`placeholder`	Um espaço reservado semitransparente interpretado no campo quando vazio.	Opcional	String	String vazia
`value`	Texto pré-preenchido no campo.	Opcional	String

Validações

Para o valor da chave validations, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`required`	Impede o envio do formulário até que o elemento seja concluído.	Optional	Boolean	false

Exemplo

YAML

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`

Você pode usar um elemento dropdown para adicionar um menu suspenso ao formulário.

Atributos

Para o valor da chave attributes, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão
`label`	Uma breve descrição da entrada esperada do usuário, que é exibida no formulário.	Obrigatório	String
`description`	Uma descrição do menu suspenso para fornecer contexto ou orientação extra, que é exibida no formulário.	Opcional	String	String vazia
`multiple`	Determina se o usuário pode selecionar mais de uma opção.	Opcional	Boolean	false
`options`	Uma matriz de opções que o usuário pode escolher. Não pode estar vazio e todas as escolhas devem ser distintas.	Obrigatório	Matriz de cadeia de caracteres

Validações

Para o valor da chave validations, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`required`	Impede o envio do formulário até que o elemento seja concluído.	Optional	Boolean	false

Exemplo

YAML

body:
- type: dropdown
  id: download
  attributes:
    label: How did you download the software?
    options:
      - Homebrew
      - MacPorts
      - apt-get
      - Built from source
  validations:
    required: true

`checkboxes`

Você pode usar o elemento checkboxes para adicionar um conjunto de caixas de seleção ao formulário.

Atributos

Para o valor da chave attributes, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão
`label`	Uma breve descrição da entrada esperada do usuário, que é exibida no formulário.	Obrigatório	String
`description`	Uma descrição do conjunto de caixas de seleção, que é exibida no formulário. É compatível com a formatação de markdown.	Opcional	String	String vazia
`options`	Uma matriz de caixas de seleção que o usuário pode selecionar. Para a sintaxe, veja abaixo.	Obrigatório	Array

Para cada valor da matriz options, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Opções
`label`	O identificador da opção, que é exibido no formulário. O Markdown é compatível com a formatação de texto em negrito ou itálico e hiperlinks.	Obrigatório	String

Validações

Para o valor da chave validations, você pode definir as chaves a seguir.

Chave	Descrição	Obrigatório	Tipo	Padrão	Valores válidos
`required`	Impede o envio do formulário até que o elemento seja concluído.	Optional	Boolean	false

Exemplo

YAML

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

Leitura adicional

YAML

Sintaxe para o esquema de formulário do GitHub

In this article

Sobre o esquema de formulário de GitHub

simétricas

markdown

Atributos

Exemplo

textarea

Atributos

Validações

Exemplo

input

Atributos

Validações

Exemplo

dropdown

Atributos

Validações

Exemplo

checkboxes

Atributos

Validações

Exemplo

Leitura adicional

`markdown`

`textarea`

`input`

`dropdown`

`checkboxes`