Nota: 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 "Configurando modelos de problemas em 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.
- 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!"
simétricas
Para cada elemento de formulário, você pode definir as seguintes chaves.
| Chave | Descrição | Obrigatório | Tipo | Padrão | Valores válidos |
|---|---|---|---|---|---|
type | O tipo de elemento que você deseja definir. | Cadeia de caracteres |
| ||
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. | Cadeia de caracteres | |||
attributes | Um conjunto de pares chave-valor que definem as propriedades do elemento. | Map | |||
validations | Um conjunto de pares chave-valor que define restrições sobre o elemento. | Map |
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 markdown
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. | Cadeia de caracteres |
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 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
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 textarea
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. | Cadeia de caracteres | |||
description | Uma descrição da área de texto para fornecer contexto ou orientação, que é exibida no formulário. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
placeholder | Um marcador semi-opaco interpretado na área de texto quando vazio. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
value | Texto pré-preenchido na área de texto. | Cadeia de caracteres | |||
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. | Cadeia de caracteres | Linguagens conhecidas para GitHub. Para obter mais informações, confira o arquivo YAML de linguagens. |
Validações para textarea
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. Somente para repositórios públicos. | Boolean | false |
Exemplo 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
Você pode usar um elemento input para adicionar um campo de texto de linha única ao formulário.
Atributos para input
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. | Cadeia de caracteres | |||
description | Uma descrição do campo para fornecer contexto ou orientação, que é exibida no formulário. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
placeholder | Um espaço reservado semitransparente interpretado no campo quando vazio. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
value | Texto pré-preenchido no campo. | Cadeia de caracteres |
Validações para input
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. Somente para repositórios públicos. | Boolean | false |
Exemplo 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
Você pode usar um elemento dropdown para adicionar um menu suspenso ao formulário.
Atributos para dropdown
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 é exibida no formulário. | Cadeia de caracteres | |||
description | Uma descrição do menu suspenso para fornecer contexto ou orientação extra, que é exibida no formulário. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
multiple | Determina se o usuário pode selecionar mais de uma opção. | Booliano | 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. | Matriz de cadeia de caracteres | |||
default | Índice da opção pré-selecionada na matriz options. Quando uma opção padrão é especificada, você não pode incluir "Nenhum" ou "n/d" como opções. | Inteiro |
Validações para dropdown
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. Somente para repositórios públicos. | Boolean | false |
Exemplo 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
Você pode usar o elemento checkboxes para adicionar um conjunto de caixas de seleção ao formulário.
Atributos para checkboxes
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 é exibida no formulário. | Cadeia de caracteres | |||
description | Uma descrição do conjunto de caixas de seleção, que é exibida no formulário. É compatível com a formatação de markdown. | Cadeia de caracteres | Cadeia de caracteres vazia | ||
options | Uma matriz de caixas de seleção que o usuário pode selecionar. Para a sintaxe, veja abaixo. | 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. | Cadeia de caracteres | |||
required | Impede o envio do formulário até que o elemento seja concluído. Somente para repositórios públicos. | Boolean | false |
Validações para checkboxes
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. Somente para repositórios públicos. | Boolean | false |
Exemplo 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