Sintaxe para o esquema de formulário do GitHub

Você pode usar o esquema de formulário de GitHub para configurar formulários para funcionalidades compatíveis.

Observação: O esquema de formulário de GitHub encontra-se atualmente na versão beta e está 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, consulte "Configurando modelos de problema 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. Nós exigimos
      que todos concordem com isso.
    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!"

Chaves

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

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
tipoO tipo de elemento que você deseja definir.Obrigatóriostring
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idO identificador para o elemento, exceto quando tipo é definido como markdown. Só é possível usar caracteres alfanuméricos, - e _. Deve ser único na definição da forma. Se fornecido, o ID é o identificador canônico para o campo no parâmetro de consulta da URL.Opcionalstring
attributesUm conjunto de pares chave-valor que definem as propriedades do elemento.ObrigatórioHash
validaçõesUm conjunto de pares chave-valor que define restrições sobre o elemento.OpcionalHash

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

TipoDescrição
markdownO texto do markdown exibido no formulário para fornecer um contexto adicional ao usuário, mas não é enviado.
textareaUm campo de texto linha múltipla.
entradaUm campo de texto de linha única.
suspensoUm menu suspenso.
caixas de seleçãoUm conjunto de caixas de seleção.

markdown

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

Atributos

Para o valor da chave `atributos`, você pode definir as seguintes chaves.

Tecla Descrição Obrigatório Tipo Padrão Valores válidos
valor`

Dicas: O processamento do YAML tratará o símbolo 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
  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 linha múltipla ao seu formulário. Os colaboradores também podem anexar arquivos aos campos textarea.

Atributos

Para o valor da chave atributos, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
etiquetaUma breve descrição da entrada esperada do usuário, que também é exibida no formulário.Obrigatóriostring
descriçãoUma descrição da área de texto para fornecer contexto ou orientação, que é exibida no formulário.OpcionalstringString vazia
espaço reservadoUm marcador semi-opaco interpretado na área de texto quando vazio.OpcionalstringString vazia
valorTexto pré-preenchido na área de texto.Opcionalstring
renderSe 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.OpcionalstringLinguagens conhecidas para GitHub. Para obter mais informações, consulte o arquivo de linguagens do YAML.

Validações

Para o valor da chave validações, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
requiredevita o envio do formulário até que o elemento seja concluído.OptionalBooleanfalse

Exemplo

YAML
body:
- type: textarea
  id: repro
  attributes:
    label: Reproduction steps
    description: "How do you trigger this bug? Apresente-nos o passo a passo."
    value: |
      1.
      2.
      3.
      ...
    render: bash
  validations:
    required: true

entrada

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

Atributos

Para o valor da chave atributos, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
etiquetaUma breve descrição da entrada esperada do usuário, que também é exibida no formulário.Obrigatóriostring
descriçãoUma descrição do campo para fornecer contexto ou orientação, que é exibida no formulário.OpcionalstringString vazia
espaço reservadoUm espaço reservado semitransparente interpretado no campo quando vazio.OpcionalstringString vazia
valorTexto pré-preenchido no campo.Opcionalstring

Validações

Para o valor da chave validações, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
requiredevita o envio do formulário até que o elemento seja concluído.OptionalBooleanfalse

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 user account page (1-2 times a week)"
  validations:
    required: true

suspenso

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

Atributos

Para o valor da chave atributos, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
etiquetaUma breve descrição da entrada esperada do usuário, que é exibida no formulário.Obrigatóriostring
descriçãoUma descrição do menu suspenso para fornecer contexto ou orientação extra, que é exibida no formulário.OpcionalstringString vazia
múltiploDetermina se o usuário pode selecionar mais de uma opção.OpcionalBooleanofalso
optionsUma matriz de opções que o usuário pode escolher. Não pode estar vazio e todas as escolhas devem ser distintas.ObrigatórioString da matriz

Validações

Para o valor da chave validações, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
requiredevita o envio do formulário até que o elemento seja concluído.OptionalBooleanfalse

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

caixas de seleção

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

Atributos

Para o valor da chave atributos, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoValores válidos
etiquetaUma breve descrição da entrada esperada do usuário, que é exibida no formulário.Opcionalstring
descriçãoUma descrição do conjunto de caixas de seleção, que é exibida no formulário. É compatível com a formatação de markdown.OpcionalstringString vazia
optionsUma matriz de caixas de seleção que o usuário pode selecionar. Para a sintaxe, veja abaixo.ObrigatórioArray

Para cada valor na matriz de opções, você pode definir as seguintes chaves.

TeclaDescriçãoObrigatórioTipoPadrãoOpções
etiquetaO 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óriostring
requiredevita o envio do formulário até que o elemento seja concluído.OptionalBooleanfalse

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

Leia mais

Esse documento ajudou você?

Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.