Skip to main content

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

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
typeO tipo de elemento que você deseja definir.ObrigatórioString
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idO 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.OpcionalString
attributesUm conjunto de pares chave-valor que definem as propriedades do elemento.ObrigatórioHash
validationsUm 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
markdownTexto Markdown exibido no formulário para fornecer contexto extra ao usuário, mas que não é enviado.
textareaUm campo de texto linha múltipla.
inputUm campo de texto de linha única.
dropdownUm menu suspenso.
checkboxesUm 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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
valueO texto que é interpretado. A formatação de Markdown é compatível.ObrigatórioString

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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
labelUma breve descrição da entrada esperada do usuário, que também é exibida no formulário.ObrigatórioString
descriptionUma descrição da área de texto para fornecer contexto ou orientação, que é exibida no formulário.OpcionalStringString vazia
placeholderUm marcador semi-opaco interpretado na área de texto quando vazio.OpcionalStringString vazia
valueTexto 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, confira o arquivo YAML de linguagens.

Validações

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

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
requiredImpede 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? 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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
labelUma breve descrição da entrada esperada do usuário, que também é exibida no formulário.ObrigatórioString
descriptionUma descrição do campo para fornecer contexto ou orientação, que é exibida no formulário.OpcionalStringString vazia
placeholderUm espaço reservado semitransparente interpretado no campo quando vazio.OpcionalStringString vazia
valueTexto pré-preenchido no campo.OpcionalString

Validações

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

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
requiredImpede 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 personal account page (1-2 times a week)"
  validations:
    required: true

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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
labelUma breve descrição da entrada esperada do usuário, que é exibida no formulário.ObrigatórioString
descriptionUma descrição do menu suspenso para fornecer contexto ou orientação extra, que é exibida no formulário.OpcionalStringString vazia
multipleDetermina se o usuário pode selecionar mais de uma opção.OpcionalBooleanfalse
optionsUma matriz de opções que o usuário pode escolher. Não pode estar vazio e todas as escolhas devem ser distintas.ObrigatórioMatriz de cadeia de caracteres

Validações

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

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
requiredImpede 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

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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
labelUma breve descrição da entrada esperada do usuário, que é exibida no formulário.ObrigatórioString
descriptionUma 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 da matriz options, você pode definir as chaves a seguir.

ChaveDescriçãoObrigatórioTipoPadrãoOpções
labelO 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

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