GitHub 表单架构语法

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

本文内容

注意

GitHub 的表单架构目前处于公开预览阶段，可能会发生变化。

关于 GitHub 的表单架构

您可以使用 GitHub 的表单架构为支持的功能配置表单。有关更多信息，请参阅“为您的仓库配置 Issue 模板”。

表单是一组用于请求用户输入的元素。您可以通过创建 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 数组中预选选项的索引。指定默认选项时，您不能包含“无”或“n/a”作为选项。整数

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预期用户输入的简短描述，显示在表单中。字符串
description复选框集的描述，显示在表单中。支持 Markdown 格式。

字符串空字符串
options用户可以选择的一组复选框。有关语法，请参见下文。数组

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

键描述必需类型默认值选项
label选项的标识符，在表单中显示。支持 Markdown 的粗体或斜体文本格式以及超链接。字符串
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

进一步阅读