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

Примечание.

Схема формы 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!"

- 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.		Строка

Совет

Обработка 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.

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

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

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 можно задать следующие ключи.

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

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

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

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

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

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

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

YAML

В этой статье