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)
    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您要定义的元素类型。字符串
  • 复选框
  • 下拉菜单
  • 输入
  • Markdown
  • 文本区域
id元素的标识符，除了当 type 设置为 markdown 时。只能使用字母数字字符、- 和 _。在表单定义中必须是唯一的。如果提供，id 是 URL 查询参数预填充中字段的规范标识符。字符串
attributes一组键值对，用于定义元素的属性。映射
validations一组键值对，用于设置元素的约束。映射

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

类型描述
Markdown在表单中显示的 Markdown 文本，用于向用户提供额外的上下文，但不会提交。
文本区域多行文本字段。
输入单行文本字段。
下拉菜单下拉菜单。
复选框一组复选框。

markdown

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

markdown 的属性

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

键描述必需类型默认值有效值
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.

textarea

您可以使用 textarea 元素在表单中添加多行文本字段。贡献者也可以在 textarea 字段中附加文件。

textarea 的属性

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

键描述必需类型默认值有效值
label对预期用户输入的简要描述，也会显示在表单中。字符串
description对文本区域的描述，用于提供上下文或指导，也会显示在表单中。字符串空字符串
placeholder当文本区域为空时，在其中呈现的半透明占位符。字符串空字符串
value预先填充在文本区域中的文本。字符串
render如果提供值，则提交的文本将被格式化为代码块。当提供此键时，文本区域不会扩展以用于文件附件或 Markdown 编辑。字符串GitHub 知道的语言。有关更多信息，请参阅 语言 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对预期用户输入的简要描述，也会显示在表单中。字符串
description对字段的描述，用于提供上下文或指导，也会显示在表单中。字符串空字符串
placeholder当字段为空时，在其中呈现的半透明占位符。字符串空字符串
value预先填充在字段中的文本。字符串

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对预期用户输入的简要描述，也会显示在表单中。字符串
description对下拉菜单的描述，用于提供额外上下文或指导，也会显示在表单中。字符串空字符串
multiple确定用户是否可以选择多个选项。布尔值false
options用户可以选择的一组选项。不能为空，所有选项必须是不同的。字符串数组
defaultoptions 数组中预选选项的索引。当指定默认选项时，您不能包含“None”或“n/a”作为选项。整数

下拉菜单 的验证

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

键描述必需类型默认值有效值
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

复选框

您可以使用 复选框 元素在表单中添加一组复选框。

复选框 的属性

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

键描述必需类型默认值有效值
label对预期用户输入的简要描述，也会显示在表单中。字符串
description复选框集的描述，显示在表单中。支持 Markdown 格式。字符串空字符串
options用户可以选择的一组复选框。有关语法，请参见下文。数组

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

键描述必需类型默认值选项
label选项的标识符，显示在表单中。支持 Markdown 格式的粗体或斜体文本，以及超链接。字符串
required在元素完成之前阻止表单提交。仅适用于公共仓库。布尔值false

复选框 的验证

对于 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

进一步阅读