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定义元素属性的一组键值对。Map
validations设置元素约束的一组键值对。Map

您可以从以下表单元素类型中进行选择。每种类型都有独特的属性和验证。

类型描述
markdown在表单中显示以向用户提供额外上下文的 Markdown 文本，但不会提交。
textarea一个多行文本字段。
input一个单行文本字段。
dropdown一个下拉菜单。
checkboxes一组复选框。
upload一个文件上传字段。

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在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse

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在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse

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确定用户是否可以选择多个选项。Booleanfalse
options用户可以选择的选项数组。不能为空，所有选项必须不同。String array
defaultoptions 数组中预选选项的索引。指定默认选项时，不能包含“None”或“n/a”作为选项。Integer

dropdown 的验证

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

键描述是否必填类型默认值有效值
required在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse

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 数组中的每个值，您可以设置以下键。

键描述是否必填类型默认值Options
label选项的标识符，显示在表单中。Markdown 支持粗体或斜体文本格式以及超链接。字符串
required在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse

checkboxes 的验证

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

键描述是否必填类型默认值有效值
required在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse

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 元素向表单添加文件上传字段。贡献者可以直接在表单中拖放文件或点击浏览并选择文件。

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

接受以下文件类型，但需遵守以下大小限制

分类扩展插件大小限制
Archives.zip、.gz、.tar.gz25 MB
Documents.pdf、.docx、.xlsx、.pptx25 MB
Images.png、.jpg、.jpeg、.gif、.svg、.webp10 MB
Videos.mp4、.mov、.webm100 MB
Text.json、.py、.js、.ts、.log、.txt、.csv25 MB

upload 的属性

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

键描述是否必填类型默认值有效值
label对预期文件上传的简要描述，显示在表单中。字符串
description对文件上传字段的描述，提供上下文或指导，显示在表单中。字符串空字符串

upload 的验证

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

键描述是否必填类型默认值有效值
required在元素完成之前阻止表单提交。仅适用于公共存储库。Booleanfalse
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"

延伸阅读

© . This site is unofficial and not affiliated with GitHub, Inc.