Skip to main content

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:
      - label: 1.0.2 (Default)
      - label: 1.0.3 (Edge)
  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,为用户提供额外的上下文,但不提交。

属性

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

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

提示:YAML 处理将哈希符号视为评论。 要插入 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 字段中附加文件。

属性

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

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

验证

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

密钥说明必需类型默认有效值
required防止在元素完成之前提交表单。OptionalBooleanfalse

示例

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 元素向表单添加单行文本字段。

属性

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

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

验证

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

密钥说明必需类型默认有效值
required防止在元素完成之前提交表单。OptionalBooleanfalse

示例

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 元素在表单中添加下拉菜单。

属性

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

密钥说明必需类型默认有效值
label预期用户输入的简短描述,以表单形式显示。必须String
description提供上下文或指导的下拉列表的描述,以表单形式显示。可选String空字符串
multiple确定用户是否可以选择多个选项。可选Booleanfalse
options用户可以选择的选项阵列。 不能为空,所有选择必须是不同的。必需字符串数组

验证

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

密钥说明必需类型默认有效值
required防止在元素完成之前提交表单。OptionalBooleanfalse

示例

YAML
body:
- type: dropdown
  id: download
  attributes:
    label: How did you download the software?
    options:
      - Homebrew
      - MacPorts
      - apt-get
      - Built from source
  validations:
    required: true

checkboxes

可以使用 checkboxes 元素向表单添加一组复选框。

属性

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

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

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

密钥说明必需类型默认选项
label选项的标识符,显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。必须String

示例

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

延伸阅读