Note
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 |
Tip
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