Skip to main content

Синтаксис для схемы формы GitHub

Для настройки форм для поддерживаемых возможностей можно использовать схему формы GitHub.

Note

Схема формы GitHubв настоящее время находится в public preview и подлежит изменению.

Сведения о схеме формы GitHub

Для настройки форм для поддерживаемых возможностей можно использовать схему формы GitHub. Дополнительные сведения см. в разделе Настройка шаблонов проблем для репозитория.

Форма — это набор элементов для запроса данных, введенных пользователем. Вы можете настроить форму, создав определение формы YAML, которое представляет собой массив элементов формы. Каждый элемент формы представляет собой набор пар "ключ-значение", определяющих тип элемента, свойства элемента и ограничения, которые необходимо применить к элементу. Для некоторых ключей значением является другой набор пар "ключ-значение".

Например, следующее определение формы включает четыре элемента формы: текстовую область для предоставления операционной системы пользователя, раскрывающееся меню для выбора версии программного обеспечения, запущенной пользователем, флажок для подтверждения правил поведения и Markdown, который благодарит пользователя за завершение формы.

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

Ключи

Для каждого элемента формы можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
typeТип элемента, который требуется определить.Строка
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idИдентификатор элемента, за исключением случаев, когда для type задано значение markdown. Может использовать только буквенно-цифровые символы, - и _. Должен быть уникальным в определении формы. Если он указан, то id является каноническим идентификатором поля в параметре запроса URL-адреса, который предварительно заполняется.Строка
attributesНабор пар "ключ-значение", определяющих свойства элемента.Карта
validationsНабор пар "ключ-значение", устанавливающих ограничения для элемента.Карта

Вы можете выбрать из следующих элементов формы. Для каждого типа существуют уникальные атрибуты и проверки.

ТипОписание
markdownТекст Markdown, который отображается в форме, чтобы предоставить пользователю дополнительный контекст, но который не отправляется.
textareaМногострочное текстовое поле.
inputТекстовое поле с одной строкой.
dropdownРаскрывающееся меню.
checkboxesНабор флажков.

markdown

Элемент markdown можно использовать для отображения Markdown в форме, которая предоставляет пользователю дополнительный контекст, но которая не отправляется.

Атрибуты для markdown

Для значения ключа attributes можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
valueТекст, преобразованный для просмотра. Поддерживается форматирование Markdown.Строка

Tip

Обработка YAML будет рассматривать хэш-символ как комментарий. Чтобы вставить заголовки Markdown, заключите текст в кавычки.

Для многострочного текста с можно использовать оператор канала.

Пример 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

Элемент textarea можно использовать для добавления в форму многострочного текстового поля. Участники также могут вкладывать файлы в поля textarea.

Атрибуты для textarea

Для значения ключа attributes можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
labelКраткое описание ожидаемых данных, введенных пользователем, которые также отображаются в форме.Строка
descriptionОписание текстовой области для предоставления контекста или руководства, которое отображается в форме.СтрокаПустая строка
placeholderПолупрозрачный заполнитель, который преобразует текстовую область для просмотра при отсутствии значения.СтрокаПустая строка
valueТекст, предварительно заполненный в текстовой области.Строка
renderЕсли указано значение, отправленный текст будет отформатирован в блок кода. Если указан этот ключ, текстовая область не будет расширяться для вложений файлов или редактирования Markdown.СтрокаЯзыки, известные GitHub. Дополнительные сведения см. в файле YAML для языков.

Проверки для textarea

Для значения ключа validations можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
requiredПредотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев.Логическийfalse

Пример 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

Элемент input можно использовать для добавления в форму текстового поля с одной строкой.

Атрибуты для input

Для значения ключа attributes можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
labelКраткое описание ожидаемых данных, введенных пользователем, которые также отображаются в форме.Строка
descriptionОписание поля для предоставления контекста или руководства, которое отображается в форме.СтрокаПустая строка
placeholderПолупрозрачный заполнитель, который отображается в поле при пустом значении.СтрокаПустая строка
valueТекст, предварительно заполненный в поле.Строка

Проверки для input

Для значения ключа validations можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
requiredПредотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев.Логическийfalse

Пример 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

Элемент dropdown можно использовать для добавления раскрывающегося меню в форму.

Атрибуты для dropdown

Для значения ключа attributes можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
labelКраткое описание ожидаемых данных, введенных пользователем, которые отображаются в форме.Строка
descriptionОписание раскрывающегося списка для предоставления дополнительного контекста или руководства, которое отображается в форме.СтрокаПустая строка
multipleОпределяет, может ли пользователь выбрать несколько вариантов.Логическийfalse
optionsМассив вариантов, которые может выбрать пользователь. Не может быть пустым, а все варианты должны быть уникальными.Массив строк
defaultИндекс предварительно выбранного параметра в массиве options . Если указан параметр по умолчанию, в качестве параметров нельзя включить "Нет" или "n/a".Целое

Проверки для dropdown

Для значения ключа validations можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
requiredПредотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев.Логическийfalse

Пример 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

Элемент checkboxes можно использовать для добавления набора флажков в форму.

Атрибуты для checkboxes

Для значения ключа attributes можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
labelКраткое описание ожидаемых данных, введенных пользователем, которые отображаются в форме.Строка
descriptionОписание набора флажков, отображаемых в форме. Поддерживает форматирование Markdown.СтрокаПустая строка
optionsМассив флажков, которые может выбрать пользователь. Сведения о синтаксисе см. далее.Массив

Для каждого значения в массиве options можно задать указанные ниже ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Параметры
labelИдентификатор параметра, который отображается в форме. Markdown поддерживается для форматирования текста, выделенного полужирным шрифтом или курсивом, и гиперссылок.Строка
requiredПредотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев.Логическийfalse

Проверки для checkboxes

Для значения ключа validations можно задать следующие ключи.

Ключ.DescriptionОбязательное полеТипПо умолчанию.Допустимые значения
requiredПредотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев.Логическийfalse

Пример 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

Дополнительные материалы