**注意：**GitHub 的表单架构目前为 公共预览版，可能会更改。
关于 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!"
密钥
对于每个表单元素，您可以设置以下键。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
type | 您想要定义的元素类型。 | String |
| ||
id | 元素的标识符，除非 type 设置为 markdown。 只能使用字母数字字符、- 和 _。 在表单定义中必须是唯一的。 如果提供，id 是 URL 查询参数预填中字段的规范标识符。 | String | |||
attributes | 定义元素属性的一组键值对。 | 映射 | |||
validations | 设置元素约束的一组键值对。 | 映射 |
您可以从以下类型的表单元素中选择。 每个类型都有唯一的属性和验证。
| 类型 | 说明 |
|---|---|
markdown | Markdown 文本显示在表单中，为用户提供额外的上下文，但并未提交。 |
textarea | 多行文本字段。 |
input | 单行文本字段。 |
dropdown | 下拉菜单。 |
checkboxes | 一组复选框。 |
markdown
可以使用 markdown 元素在表单中显示 Markdown，为用户提供额外的上下文，但不提交。
markdown 的属性
对于 attributes 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
value | 渲染的文本。 支持 Markdown 格式。 | String |
提示：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 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
label | 预期用户输入的简短描述，也以表单形式显示。 | String | |||
description | 提供上下文或指导的文本区域的描述，以表单形式显示。 | String | 空字符串 | ||
placeholder | 半透明的占位符，在文本区域空白时呈现。 | String | 空字符串 | ||
value | 在文本区域中预填充的文本。 | String | |||
render | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | String | GitHub 已知的语言。 有关详细信息，请参阅语言 YAML 文件。 |
textarea 的验证
对于 validations 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
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 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
label | 预期用户输入的简短描述，也以表单形式显示。 | String | |||
description | 提供上下文或指导的字段的描述，以表单形式显示。 | String | 空字符串 | ||
placeholder | 半透明的占位符，在字段空白时呈现。 | String | 空字符串 | ||
value | 字段中预填的文本。 | String |
input 的验证
对于 validations 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
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 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
label | 预期用户输入的简短描述，以表单形式显示。 | String | |||
description | 提供上下文或指导的下拉列表的描述，以表单形式显示。 | String | 空字符串 | ||
multiple | 确定用户是否可以选择多个选项。 | Boolean | false | ||
options | 用户可以选择的选项阵列。 不能为空，所有选择必须是不同的。 | 字符串数组 | |||
default | options 数组中预选选项的索引。 指定了默认选项时，不能包含“None”或“n/a”作为选项。 | Integer |
dropdown 的验证
对于 validations 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
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 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
label | 预期用户输入的简短描述，以表单形式显示。 | String | |||
description | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | String | 空字符串 | ||
options | 用户可以选择的复选框阵列。 有关语法，请参阅下文。 | Array |
对于 options 数组中的每个值，可以设置以下键。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 选项 |
|---|---|---|---|---|---|
label | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | String | |||
required | 防止在元素完成之前提交表单。 仅适用于公共存储库。 | 布尔 | false |
checkboxes 的验证
对于 validations 键的值，可以设置以下密钥。
| 密钥 | 说明 | 必需 | 类型 | 默认 | 有效值 |
|---|---|---|---|---|---|
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