Skip to main content
Мы публикуем частые обновления нашей документации, и перевод этой страницы может все еще выполняться. Актуальные сведения см. в документации на английском языке.

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

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

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

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

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

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

markdown

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

Атрибуты

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

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

Советы. Обработка YAML будет рассматривать хэш-символ как комментарий. Чтобы вставить заголовки 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.

Атрибуты

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

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

Проверки

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

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

Пример

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 можно использовать для добавления в форму текстового поля с одной строкой.

Атрибуты

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

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

Проверки

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

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

Пример

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 можно использовать для добавления раскрывающегося меню в форму.

Атрибуты

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

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

Проверки

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

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

Пример

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

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

Атрибуты

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

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

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

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

Проверки

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

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

Пример

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

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