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您想要定义的元素类型。字符串
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
  • upload
id元素的标识符，除非 type 设置为 markdown。 只能使用字母数字字符、- 和 _。 在表单定义中必须是唯一的。 如果提供，id 是 URL 查询参数预填中字段的规范标识符。字符串
attributes定义元素属性的一组键值对。地图
validations一组用于设置元素限制的键值对。地图

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

类型说明
markdownMarkdown 文本显示在表单中，为用户提供额外的上下文，但并未提交。
textarea多行文本字段。
input单行文本字段。
dropdown下拉菜单。
checkboxes一组复选框。
upload文件上传字段。

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确定用户是否可以选择多个选项。布尔假
options用户可以选择的选项阵列。 不能为空，所有选择必须是不同的。字符串数组
default
          `options` 数组中预选选项的索引。 指定了默认选项时，不能包含“None”或“n/a”作为选项。  | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="Optional" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg>  | 整数 | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-dash" aria-label="dash icon" role="img"><path d="M2 7.75A.75.75 0 0 1 2.75 7h10a.75.75 0 0 1 0 1.5h-10A.75.75 0 0 1 2 7.75Z"></path></svg> | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-dash" aria-label="dash icon" role="img"><path d="M2 7.75A.75.75 0 0 1 2.75 7h10a.75.75 0 0 1 0 1.5h-10A.75.75 0 0 1 2 7.75Z"></path></svg> |


          `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用户可以选择的复选框阵列。 有关语法，请参阅下文。Array

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

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

          `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

upload

可以使用 upload 元素将文件上传字段添加到窗体。 参与者可以拖放文件，也可以单击以直接在窗体中浏览并选择文件。

支持的文件类型和大小限制

接受以下文件类型，但受以下大小限制的约束：

类别Extensions大小限制
档案
          `.zip`、`.gz`、`.tar.gz` | 25 MB |

| 文档 | .pdf、.docx、.xlsx、.pptx | 25 MB | | 映像 | .png、.jpg、.jpeg、.gif、.svg、.webp | 10 MB | | Videos | .mp4、.mov、.webm | 100 MB | | 文本 | .json、.py、.js、.ts、.log、.txt、.csv | 25 MB |

          `upload` 的属性

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

密钥说明必选类型默认有效值
label关于文件上传过程的简要说明，显示在表单中。字符串
description提供上下文或指导的文件上传字段的描述，以表单形式显示。字符串空字符串

          `upload` 的验证

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

密钥说明必选类型默认有效值
required防止在元素完成之前提交表单。 仅适用于公共存储库。布尔false
accept接受的文件扩展名的逗号分隔列表。 如果省略，则接受所有受支持的文件类型。字符串

          `upload` 的示例
YAML
body:
- type: upload
  id: screenshots
  attributes:
    label: Upload relevant files
    description: "Drag and drop any relevant screenshots or log files."
  validations:
    required: false
    accept: ".png,.jpg,.gif,.log,.txt,.zip"

延伸阅读