code.gitea.io/gitea@v1.22.3/docs/content/usage/issue-pull-request-templates.zh-cn.md (about) 1 --- 2 date: "2022-09-07T16:00:00+08:00" 3 title: "工单与合并请求模板" 4 slug: "issue-pull-request-templates" 5 sidebar_position: 15 6 toc: true 7 draft: false 8 aliases: 9 - /zh-cn/issue-pull-request-templates 10 menu: 11 sidebar: 12 parent: "usage" 13 name: "工单与合并请求模板" 14 sidebar_position: 15 15 identifier: "issue-pull-request-templates" 16 --- 17 18 # 从模板创建工单与合并请求 19 20 开发者可以利用问题模板创建工单与合并请求，其目的在于规范参与者的语言表达。 21 22 ## 模板介绍 23 24 Gitea 支持两种格式的模板：Markdown 和 YAML。 25 26 ### Markdown 模板 27 28 在 Gitea 中存在两种用途的 Markdown 模板： 29 30 - `ISSUE_TEMPLATE/bug-report.md` 用于规范工单的 Markdown 文本描述 31 - `PULL_REQUEST_TEMPLATE.md` 用于规范合并请求的 Markdown 文本描述 32 33 对于以上 Markdown 模板，我们推荐您将它们放置到项目目录 `.gitea` 进行收纳。 34 35 ### YAML 模板 36 37 用 YAML 语法编写的模板相比 Markdown 可以实现更丰富的功能，利用表单实现诸如：问卷调查、字符校验。在 Gitea 中的 YAML 同样支持两种用途： 38 39 - `ISSUE_TEMPLATE/bug-report.yaml` 用于创建问卷调查形式的工单 40 - `PULL_REQUEST_TEMPLATE.yaml` 用于创建表单形式的合并请求 41 42 对于以上 YAML 模板，我们同样推荐您将它们放置到项目目录 `.gitea` 进行收纳。 43 44 ##### 表单支持通过 URL 查询参数传值 45 46 当新建工单页面 URL 以 `?title=Issue+Title&body=Issue+Text` 为查询参数，表单将使用其中的参数（key-value）填充表单内容。 47 48 ### Gitea 支持的模板文件路径 49 50 工单模板文件名: 51 52 - `ISSUE_TEMPLATE.md` 53 - `ISSUE_TEMPLATE.yaml` 54 - `ISSUE_TEMPLATE.yml` 55 - `issue_template.md` 56 - `issue_template.yaml` 57 - `issue_template.yml` 58 - `.gitea/ISSUE_TEMPLATE.md` 59 - `.gitea/ISSUE_TEMPLATE.yaml` 60 - `.gitea/ISSUE_TEMPLATE.yml` 61 - `.gitea/issue_template.md` 62 - `.gitea/issue_template.yaml` 63 - `.gitea/issue_template.yml` 64 - `.github/ISSUE_TEMPLATE.md` 65 - `.github/ISSUE_TEMPLATE.yaml` 66 - `.github/ISSUE_TEMPLATE.yml` 67 - `.github/issue_template.md` 68 - `.github/issue_template.yaml` 69 - `.github/issue_template.yml` 70 71 合并请求模板: 72 73 - `PULL_REQUEST_TEMPLATE.md` 74 - `PULL_REQUEST_TEMPLATE.yaml` 75 - `PULL_REQUEST_TEMPLATE.yml` 76 - `pull_request_template.md` 77 - `pull_request_template.yaml` 78 - `pull_request_template.yml` 79 - `.gitea/PULL_REQUEST_TEMPLATE.md` 80 - `.gitea/PULL_REQUEST_TEMPLATE.yaml` 81 - `.gitea/PULL_REQUEST_TEMPLATE.yml` 82 - `.gitea/pull_request_template.md` 83 - `.gitea/pull_request_template.yaml` 84 - `.gitea/pull_request_template.yml` 85 - `.github/PULL_REQUEST_TEMPLATE.md` 86 - `.github/PULL_REQUEST_TEMPLATE.yaml` 87 - `.github/PULL_REQUEST_TEMPLATE.yml` 88 - `.github/pull_request_template.md` 89 - `.github/pull_request_template.yaml` 90 - `.github/pull_request_template.yml` 91 92 #### 工单模板目录 93 94 由于工单存在多种类型，Gitea 支持将工单模板统一收纳到 `ISSUE_TEMPLATE` 目录。以下是 Gitea 支持的工单模板目录: 95 96 - `ISSUE_TEMPLATE` 97 - `issue_template` 98 - `.gitea/ISSUE_TEMPLATE` 99 - `.gitea/issue_template` 100 - `.github/ISSUE_TEMPLATE` 101 - `.github/issue_template` 102 - `.gitlab/ISSUE_TEMPLATE` 103 - `.gitlab/issue_template` 104 105 目录支持混合存放 Markdown (`.md`) 或 YAML (`.yaml`/`.yml`) 格式的工单模板。另外，合并请求模板不支持目录存放。 106 107 ## Markdown 模板语法 108 109 ```md 110 --- 111 112 name: "Template Name" 113 about: "This template is for testing!" 114 title: "[TEST] " 115 ref: "main" 116 labels: 117 118 - bug 119 - "help needed" 120 121 --- 122 123 This is the template! 124 ``` 125 126 上面的示例表示用户从列表中选择一个工单模板时，列表会展示模板名称 `Template Name` 和模板描述 `This template is for testing!`。 同时，标题会预先填充为 `[TEST]`，而正文将预先填充 `This is the template!`。 最后，Issue 还会被分配两个标签，`bug` 和 `help needed`，并且将问题指向 `main` 分支。 127 128 ## YAML 模板语法 129 130 YAML 模板格式如下，相比 Markdown 模板提供了更多实用性的功能。 131 132 ```yaml 133 name: 表单名称 134 about: 表单描述 135 title: 默认标题 136 body: 主体内容 137 type: 定义表单元素类型 138 id: 定义表单标号 139 attributes: 扩展的属性 140 validations: 内容校验 141 ``` 142 143 下例 YAML 配置文件完整定义了一个用于提交 bug 的问卷调查。 144 145 ```yaml 146 name: Bug Report 147 about: File a bug report 148 title: "[Bug]: " 149 body: 150 - type: markdown 151 attributes: 152 value: | 153 Thanks for taking the time to fill out this bug report! 154 - type: input 155 id: contact 156 attributes: 157 label: Contact Details 158 description: How can we get in touch with you if we need more info? 159 placeholder: ex. email@example.com 160 validations: 161 required: false 162 - type: textarea 163 id: what-happened 164 attributes: 165 label: What happened? 166 description: Also tell us, what did you expect to happen? 167 placeholder: Tell us what you see! 168 value: "A bug happened!" 169 validations: 170 required: true 171 - type: dropdown 172 id: version 173 attributes: 174 label: Version 175 description: What version of our software are you running? 176 options: 177 - 1.0.2 (Default) 178 - 1.0.3 (Edge) 179 validations: 180 required: true 181 - type: dropdown 182 id: browsers 183 attributes: 184 label: What browsers are you seeing the problem on? 185 multiple: true 186 options: 187 - Firefox 188 - Chrome 189 - Safari 190 - Microsoft Edge 191 - type: textarea 192 id: logs 193 attributes: 194 label: Relevant log output 195 description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks. 196 render: shell 197 - type: checkboxes 198 id: terms 199 attributes: 200 label: Code of Conduct 201 description: By submitting this issue, you agree to follow our [Code of Conduct](https://example.com) 202 options: 203 - label: I agree to follow this project's Code of Conduct 204 required: true 205 ``` 206 207 ### Markdown 段落 208 209 您可以在 YAML 模板中使用 `markdown` 元素为开发者提供额外的上下文支撑，这部分内容会作为创建工单的提示但不会作为工单内容提交。 210 211 `attributes` 子项提供了以下扩展能力： 212 213 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 214 | ------- | ------------------------------ | ---- | ------ | ------ | ------ | 215 | `value` | 渲染的文本。支持 Markdown 格式 | 必选 | 字符串 | - | - | 216 217 ### Textarea 多行文本输入框 218 219 您可以使用 `textarea` 元素在表单中添加多行文本输入框。 除了输入文本，开发者还可以在 `textarea` 区域附加文件。 220 221 `attributes` 子项提供了以下扩展能力： 222 223 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 224 | ------------- | ----------------------------------------------------------------------------------------------------- | ---- | ------ | -------- | ------------------ | 225 | `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - | 226 | `description` | 提供上下文或指导的文本区域的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - | 227 | `placeholder` | 半透明的占位符，在文本区域空白时呈现 | 可选 | 字符串 | 空字符串 | - | 228 | `value` | 在文本区域中预填充的文本。 | 可选 | 字符串 | - | - | 229 | `render` | 如果提供了值，提交的文本将格式化为代码块。 提供此键时，文本区域将不会扩展到文件附件或 Markdown 编辑。 | 可选 | 字符串 | - | Gitea 支持的语言。 | 230 231 `validations` 子项提供以下文本校验参数： 232 233 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 234 | ---------- | ---------------------------- | ---- | ------ | ------ | ------ | 235 | `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - | 236 237 ### Input 单行输入框 238 239 您可以使用 `input` 元素添加单行文本字段到表单。 240 241 `attributes` 子项提供了以下扩展能力： 242 243 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 244 | ------------- | ---------------------------------------------- | ---- | ------ | -------- | ------ | 245 | `label` | 预期用户输入的简短描述，也以表单形式显示。 | 必选 | 字符串 | - | - | 246 | `description` | 提供上下文或指导的字段的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - | 247 | `placeholder` | 半透明的占位符，在字段空白时呈现。 | 可选 | 字符串 | 空字符串 | - | 248 | `value` | 字段中预填的文本。 | 可选 | 字符串 | - | - | 249 250 `validations` 子项提供以下文本校验参数： 251 252 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 253 | ----------- | -------------------------------- | ---- | ------ | ------ | -------------------------------------------------------------- | 254 | `required` | 防止在未填内容时提交表单。 | 可选 | 布尔型 | false | - | 255 | `is_number` | 防止在未填数字时提交表单。 | 可选 | 布尔型 | false | - | 256 | `regex` | 直到满足了与正则表达式匹配的值。 | 可选 | 字符串 | - | [正则表达式](https://en.wikipedia.org/wiki/Regular_expression) | 257 258 ### Dropdown 下拉菜单 259 260 您可以使用 `dropdown` 元素在表单中添加下拉菜单。 261 262 `attributes` 子项提供了以下扩展能力： 263 264 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 265 | ------------- | --------------------------------------------------------- | ---- | ---------- | -------- | ------ | 266 | `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - | 267 | `description` | 提供上下文或指导的下拉列表的描述，以表单形式显示。 | 可选 | 字符串 | 空字符串 | - | 268 | `multiple` | 确定用户是否可以选择多个选项。 | 可选 | 布尔型 | false | - | 269 | `options` | 用户可以选择的选项列表。 不能为空，所有选择必须是不同的。 | 必选 | 字符串数组 | - | - | 270 271 `validations` 子项提供以下文本校验参数： 272 273 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 274 | ---------- | ---------------------------- | ---- | ------ | ------ | ------ | 275 | `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - | 276 277 ### Checkboxes 复选框 278 279 您可以使用 `checkboxes` 元素添加一组复选框到表单。 280 281 `attributes` 子项提供了以下扩展能力： 282 283 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 284 | ------------- | ----------------------------------------------------- | ---- | ------ | -------- | ------ | 285 | `label` | 预期用户输入的简短描述，以表单形式显示。 | 必选 | 字符串 | - | - | 286 | `description` | 复选框集的描述，以表单形式显示。 支持 Markdown 格式。 | 可选 | 字符串 | 空字符串 | - | 287 | `options` | 用户可以选择的复选框列表。 有关语法，请参阅下文。 | 必选 | 数组 | - | - | 288 289 对于 `options`，您可以设置以下参数： 290 291 | 键 | 描述 | 必选 | 类型 | 默认值 | 有效值 | 292 | ---------- | --------------------------------------------------------------------------------- | ---- | ------ | ------ | ------ | 293 | `label` | 选项的标识符，显示在表单中。 支持 Markdown 用于粗体或斜体文本格式化和超文本链接。 | 必选 | 字符串 | - | - | 294 | `required` | 防止在元素完成之前提交表单。 | 可选 | 布尔型 | false | - |