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.

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.

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!"

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.Cadeia de caracteres
  • 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.Cadeia de caracteres
attributesUm conjunto de pares chave-valor que definem as propriedades do elemento.Map
validationsUm 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.

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 markdown

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

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 textarea

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.Cadeia de caracteres
descriptionUma descrição da área de texto para fornecer contexto ou orientação, que é exibida no formulário.Cadeia de caracteresCadeia de caracteres vazia
placeholderUm marcador semi-opaco interpretado na área de texto quando vazio.Cadeia de caracteresCadeia de caracteres vazia
valueTexto pré-preenchido na área de texto.Cadeia de caracteres
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.Cadeia de caracteresLinguagens 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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
requiredImpede o envio do formulário até que o elemento seja concluído. Somente para repositórios públicos.Booleanfalse

Exemplo de textarea

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 input

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.Cadeia de caracteres
descriptionUma descrição do campo para fornecer contexto ou orientação, que é exibida no formulário.Cadeia de caracteresCadeia de caracteres vazia
placeholderUm espaço reservado semitransparente interpretado no campo quando vazio.Cadeia de caracteresCadeia de caracteres vazia
valueTexto pré-preenchido no campo.Cadeia de caracteres

Validações para input

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. Somente para repositórios públicos.Booleanfalse

Exemplo de input

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 dropdown

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.Cadeia de caracteres
descriptionUma descrição do menu suspenso para fornecer contexto ou orientação extra, que é exibida no formulário.Cadeia de caracteresCadeia de caracteres vazia
multipleDetermina se o usuário pode selecionar mais de uma opção.Boolianofalse
optionsUma 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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
requiredImpede o envio do formulário até que o elemento seja concluído. Somente para repositórios públicos.Booleanfalse

Exemplo de dropdown

YAML
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

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.

ChaveDescriçãoObrigatórioTipoPadrãoValores válidos
labelUma breve descrição da entrada esperada do usuário, que é exibida no formulário.Cadeia de caracteres
descriptionUma descrição do conjunto de caixas de seleção, que é exibida no formulário. É compatível com a formatação de markdown.Cadeia de caracteresCadeia de caracteres vazia
optionsUma 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.

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.Cadeia de caracteres
requiredImpede o envio do formulário até que o elemento seja concluído. Somente para repositórios públicos.Booleanfalse

Validações para checkboxes

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. Somente para repositórios públicos.Booleanfalse

Exemplo de checkboxes

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