GitHub 表单架构的语法

您可以使用 GitHub 的表单架构来配置支持的功能。

本文内容

注意：GitHub 的表单架构目前为 beta 版本，可能会有变动。

关于 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您想要定义的元素类型。String
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
id元素的标识符，除非 type 设置为 markdown。 只能使用字母数字字符、- 和 _。 在表单定义中必须是唯一的。 如果提供，id 是 URL 查询参数预填中字段的规范标识符。String
attributes定义元素属性的一组键值对。映射
validations设置元素约束的一组键值对。映射

您可以从以下类型的表单元素中选择。 每个类型都有唯一的属性和验证。

类型说明
markdownMarkdown 文本显示在表单中，为用户提供额外的上下文，但并未提交。
textarea多行文本字段。
input单行文本字段。
dropdown下拉菜单。
checkboxes一组复选框。

markdown

可以使用 markdown 元素在表单中显示 Markdown，为用户提供额外的上下文，但不提交。

markdown 的属性

对于 attributes 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
value渲染的文本。 支持 Markdown 格式。String

提示：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 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
label预期用户输入的简短描述，也以表单形式显示。String
description提供上下文或指导的文本区域的描述，以表单形式显示。String空字符串
placeholder半透明的占位符，在文本区域空白时呈现。String空字符串
value在文本区域中预填充的文本。String
render如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。StringGitHub 已知的语言。 有关详细信息，请参阅语言 YAML 文件。

textarea 的验证

对于 validations 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
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 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
label预期用户输入的简短描述，也以表单形式显示。String
description提供上下文或指导的字段的描述，以表单形式显示。String空字符串
placeholder半透明的占位符，在字段空白时呈现。String空字符串
value字段中预填的文本。String

input 的验证

对于 validations 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
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 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
label预期用户输入的简短描述，以表单形式显示。String
description提供上下文或指导的下拉列表的描述，以表单形式显示。String空字符串
multiple确定用户是否可以选择多个选项。Booleanfalse
options用户可以选择的选项阵列。 不能为空，所有选择必须是不同的。字符串数组
defaultoptions 数组中预选选项的索引。 指定了默认选项时，不能包含“None”或“n/a”作为选项。Integer

dropdown 的验证

对于 validations 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
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 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
label预期用户输入的简短描述，以表单形式显示。String
description复选框集的描述，以表单形式显示。 支持 Markdown 格式。String空字符串
options用户可以选择的复选框阵列。 有关语法，请参阅下文。Array

对于 options 数组中的每个值，可以设置以下键。

密钥说明必需类型默认选项
label选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。String
required防止在元素完成之前提交表单。 仅适用于公共存储库。布尔false

checkboxes 的验证

对于 validations 键的值，可以设置以下密钥。

密钥说明必需类型默认有效值
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

延伸阅读