对于开发来说,我们在收到开发工单时希望有完整的需求描述、错误日志以及问题复现方法。为了帮助提问者讲清楚他们的需求,Gitea 在新版本中推出表单和校验功能。
在最新的 dev
分支中,Gitea 的议题模板功能得到增强,用户不仅可以使用传统的 Markdown 模板创建工单与合并请求,还可以使用 YAML 模板创建预格式化的问卷调查清单。同时,1.18-rc1
将于 9 月中旬发布!
模板介绍
Gitea 支持两种格式的模板,Markdown 和 YAML。
Markdown 模板
在 Gitea 中存在两种用途的 Markdown 模板:
-
ISSUE_TEMPLATE/bug-report.md
用于规范工单的 Markdown 文本描述 -
PULL_REQUEST_TEMPLATE.md
用于规范合并请求的 Markdown 文本描述
对于以上 Markdown 模板,我们推荐您将它们放置到项目目录 .gitea
进行收纳。
YAML 模板
用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能,利用表单实现诸如:问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途:
-
ISSUE_TEMPLATE/bug-report.yaml
用于创建问卷调查形式的工单 -
PULL_REQUEST_TEMPLATE.yaml
用于创建表单形式的合并请求
对于以上 YAML 模板,我们同样推荐您将它们放置到项目目录 .gitea
进行收纳。
表单支持通过 URL 查询参数传值
当新建工单页面 URL 以 ?title=Issue+Title&body=Issue+Text
为查询参数,表单将使用其中的参数(key-value)填充表单内容。
Gitea 支持的模板文件路径
工单模板文件名:
ISSUE_TEMPLATE.md
ISSUE_TEMPLATE.yaml
ISSUE_TEMPLATE.yml
issue_template.md
issue_template.yaml
issue_template.yml
.gitea/ISSUE_TEMPLATE.md
.gitea/ISSUE_TEMPLATE.yaml
.gitea/ISSUE_TEMPLATE.yml
.gitea/issue_template.md
.gitea/issue_template.yaml
.gitea/issue_template.yml
.github/ISSUE_TEMPLATE.md
.github/ISSUE_TEMPLATE.yaml
.github/ISSUE_TEMPLATE.yml
.github/issue_template.md
.github/issue_template.yaml
.github/issue_template.yml
合并请求模板:
PULL_REQUEST_TEMPLATE.md
PULL_REQUEST_TEMPLATE.yaml
PULL_REQUEST_TEMPLATE.yml
pull_request_template.md
pull_request_template.yaml
pull_request_template.yml
.gitea/PULL_REQUEST_TEMPLATE.md
.gitea/PULL_REQUEST_TEMPLATE.yaml
.gitea/PULL_REQUEST_TEMPLATE.yml
.gitea/pull_request_template.md
.gitea/pull_request_template.yaml
.gitea/pull_request_template.yml
.github/PULL_REQUEST_TEMPLATE.md
.github/PULL_REQUEST_TEMPLATE.yaml
.github/PULL_REQUEST_TEMPLATE.yml
.github/pull_request_template.md
.github/pull_request_template.yaml
.github/pull_request_template.yml
工单模板目录
由于工单存在多种类型,Gitea 支持将工单模板统一收纳到 ISSUE_TEMPLATE
目录。以下是 Gitea 支持的工单模板目录:
ISSUE_TEMPLATE
issue_template
.gitea/ISSUE_TEMPLATE
.gitea/issue_template
.github/ISSUE_TEMPLATE
.github/issue_template
.gitlab/ISSUE_TEMPLATE
.gitlab/issue_template
目录支持混合存放 Markdown (.md
) 或 YAML (.yaml
/.yml
) 格式的工单模板。另外,合并请求模板不支持目录存放。
模板语法
Markdown 模板语法
---
name: "Template Name"
about: "This template is for testing!"
title: "[TEST] "
ref: "main"
labels:
- bug
- "help needed"
---
This is the template!
上面的示例表示用户从列表中选择一个工单模板时,列表会展示模板名称 Template Name
和模板描述 This template is for testing!
。 同时,标题会预先填充为 [TEST]
,而正文将预先填充 This is the template!
。 最后,Issue 还会被分配两个标签,bug
和 help needed
,并且将议题指向 main
分支。
YAML 模板语法
YAML 模板格式如下,相比 Markdown 模板提供了更多实用性的功能。
name: 表单名称
about: 表单描述
title: 默认标题
body: 主体内容
type: 定义表单元素类型
id: 定义表单标号
attributes: 扩展的属性
validations: 内容校验
下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。
name: Bug Report
about: File a bug report
title: "[Bug]: "
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
- type: input
id: contact
attributes:
label: Contact Details
description: How can we get in touch with you if we need more info?
placeholder: ex. email@example.com
validations:
required: false
- type: textarea
id: what-happened
attributes:
label: What happened?
description: Also tell us, what did you expect to happen?
placeholder: Tell us what you see!
value: "A bug happened!"
validations:
required: true
- type: dropdown
id: version
attributes:
label: Version
description: What version of our software are you running?
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: dropdown
id: browsers
attributes:
label: What browsers are you seeing the problem on?
multiple: true
options:
- Firefox
- Chrome
- Safari
- Microsoft Edge
- type: textarea
id: logs
attributes:
label: Relevant log output
description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
render: shell
- type: checkboxes
id: terms
attributes:
label: Code of Conduct
description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com)
options:
- label: I agree to follow this project's Code of Conduct
required: true
在 YAML 模板中包含 Markdown 格式文本描述
您可以在 YAML 模板中使用 markdown
元素为开发者提供额外的上下文支撑,这部分内容会作为创建工单的提示但不会作为工单内容提交。
attributes
子项提供了以下扩展能力:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
value |
渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | - | - |
Textarea 多行文本输入框
您可以使用 textarea
元素在表单中添加多行文本输入框。 除了输入文本,开发者还可以在 textarea
区域附加文件。
attributes
子项提供了以下扩展能力:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
label |
预期用户输入的简短描述,也以表单形式显示。 | 必选 | 字符串 | - | - |
description |
提供上下文或指导的文本区域的描述,以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
placeholder |
半透明的占位符,在文本区域空白时呈现 | 可选 | 字符串 | 空字符串 | - |
value |
在文本区域中预填充的文本。 | 可选 | 字符串 | - | - |
render |
如果提供了值,提交的文本将格式化为代码块。 提供此键时,文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | - | Gitea 支持的语言。 |
validations
子项提供以下文本校验参数:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
required |
防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
Input 单行输入框
您可以使用 input
元素添加单行文本字段到表单。
attributes
子项提供了以下扩展能力:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
label |
预期用户输入的简短描述,也以表单形式显示。 | 必选 | 字符串 | - | - |
description |
提供上下文或指导的字段的描述,以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
placeholder |
半透明的占位符,在字段空白时呈现。 | 可选 | 字符串 | 空字符串 | - |
value |
字段中预填的文本。 | 可选 | 字符串 | - | - |
validations
子项提供以下文本校验参数:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
required |
防止在未填内容时提交表单。 | 可选 | 布尔型 | false | - |
is_number |
防止在未填数字时提交表单。 | 可选 | 布尔型 | false | - |
regex |
直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | - | 正则表达式 |
Dropdown 下拉菜单
您可以使用 dropdown
元素在表单中添加下拉菜单。
attributes
子项提供了以下扩展能力:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
label |
预期用户输入的简短描述,以表单形式显示。 | 必选 | 字符串 | - | - |
description |
提供上下文或指导的下拉列表的描述,以表单形式显示。 | 可选 | 字符串 | 空字符串 | - |
multiple |
确定用户是否可以选择多个选项。 | 可选 | 布尔型 | false | - |
options |
用户可以选择的选项列表。 不能为空,所有选择必须是不同的。 | 必选 | 字符串数组 | - | - |
validations
子项提供以下文本校验参数:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
required |
防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
Checkboxes 复选框
您可以使用 checkboxes
元素添加一组复选框到表单。
attributes
子项提供了以下扩展能力:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
label |
预期用户输入的简短描述,以表单形式显示。 | 必选 | 字符串 | - | - |
description |
复选框集的描述,以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | - |
options |
用户可以选择的复选框列表。 有关语法,请参阅下文。 | 必选 | 数组 | - | - |
对于 options
,您可以设置以下参数:
键 | 描述 | 必选 | 类型 | 默认值 | 有效值 |
---|---|---|---|---|---|
label |
选项的标识符,显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | - | - |
required |
防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |
关于 Gitea
上海吉谛科技有限公司对接 Gitea 相关的商务合作,现已推出开源且自主可控的 DevOps All-in-one 解决方案。
Gitea 项目由公司创始人 Lunny 在 2016 年创建并开源,经过 5 年多的发展,在 GitHub 上获得了超过 3 万 1 千颗星,累计下载量超过 3 亿次,约 40 万使用者,获得了上千家国内外中大型企业认可并在企业中进行了部署。
- Gitea 官方技术 QQ 群:328432459
- 想要了解更多 Gitea 资讯,欢迎关注我们的公众号 Gitea