Note
Схема формы GitHubв настоящее время находится в public preview и подлежит изменению.
Сведения о схеме формы GitHub
Для настройки форм для поддерживаемых возможностей можно использовать схему формы GitHub. Дополнительные сведения см. в разделе Настройка шаблонов проблем для репозитория.
Форма — это набор элементов для запроса данных, введенных пользователем. Вы можете настроить форму, создав определение формы YAML, которое представляет собой массив элементов формы. Каждый элемент формы представляет собой набор пар "ключ-значение", определяющих тип элемента, свойства элемента и ограничения, которые необходимо применить к элементу. Для некоторых ключей значением является другой набор пар "ключ-значение".
Например, следующее определение формы включает четыре элемента формы: текстовую область для предоставления операционной системы пользователя, раскрывающееся меню для выбора версии программного обеспечения, запущенной пользователем, флажок для подтверждения правил поведения и Markdown, который благодарит пользователя за завершение формы.
- 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!"
- 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 | Тип элемента, который требуется определить. | Строка |
| ||
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
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.
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
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
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
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
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
можно использовать для добавления раскрывающегося меню в форму.
Атрибуты для dropdown
Для значения ключа attributes
можно задать следующие ключи.
Ключ. | Description | Обязательное поле | Тип | По умолчанию. | Допустимые значения |
---|---|---|---|---|---|
label | Краткое описание ожидаемых данных, введенных пользователем, которые отображаются в форме. | Строка | |||
description | Описание раскрывающегося списка для предоставления дополнительного контекста или руководства, которое отображается в форме. | Строка | Пустая строка | ||
multiple | Определяет, может ли пользователь выбрать несколько вариантов. | Логический | false | ||
options | Массив вариантов, которые может выбрать пользователь. Не может быть пустым, а все варианты должны быть уникальными. | Массив строк | |||
default | Индекс предварительно выбранного параметра в массиве options . Если указан параметр по умолчанию, в качестве параметров нельзя включить "Нет" или "n/a". | Целое |
Проверки для dropdown
Для значения ключа validations
можно задать следующие ключи.
Ключ. | Description | Обязательное поле | Тип | По умолчанию. | Допустимые значения |
---|---|---|---|---|---|
required | Предотвращает отправку формы до завершения элемента. Только для общедоступных репозиториев. | Логический | false |
Пример dropdown
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
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
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
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