跳至主要内容
版本:1.23.6

郵件模板

為了製作某些操作的電子郵件主題和內容,Gitea 可以使用模板進行自定義。這些功能的模板位於 custom 目錄下。 Gitea 有一個內部模板,作為默認值,如果沒有自定義替代品。

自定義模板在 Gitea 啟動時加載。對它們的更改在 Gitea 再次重啟之前不會被識別。

支持模板的郵件通知

目前,以下通知事件使用模板:

操作名稱用途
new創建了一個新問題或拉取請求。
comment在現有問題或拉取請求中創建了一個新評論。
close關閉了一個問題或拉取請求。
reopen重新打開了一個問題或拉取請求。
review拉取請求中的審查的主要評論。
approve拉取請求的批准審查的主要評論。
reject拉取請求的變更請求審查的主要評論。
code拉取請求中的代碼單一評論。
assigned用戶被分配到一個問題或拉取請求。
default任何不包括在上述類別中的操作,或當對應的類別模板不存在時。

特定消息類型的模板路徑為:

custom/templates/mail/{action type}/{action name}.tmpl

其中 {action type}issuepull(對於拉取請求)之一,{action name} 是上面列出的名稱之一。

例如,有關拉取請求評論的郵件的特定模板為:

custom/templates/mail/pull/comment.tmpl

但是,不需要為每個操作類型/名稱組合創建模板。 使用回退系統來選擇事件的適當模板。使用此列表中的 第一個存在的 模板:

  • 所需 操作類型操作名稱 的特定模板。
  • 操作類型 issue 和所需 操作名稱 的模板。
  • 操作類型 issue 和操作名稱 default 的模板。

唯一必需的模板是操作類型 issue 和操作名稱 default,它已嵌入 Gitea 中,除非用戶在 custom 目錄中覆蓋它。

模板語法

郵件模板是 UTF-8 編碼的文本文件,需要遵循以下格式之一:

主題行的文本和宏
------------
郵件正文的文本和宏

郵件正文的文本和宏

指定 主題 部分是可選的(因此也是破折號分隔符)。使用時,主題郵件正文 模板之間的分隔符需要至少三個破折號;分隔符行中不允許其他字符。

主題郵件正文Golang 的模板引擎 解析, 並為每個通知提供一個 元數據上下文。上下文包含以下元素:

名稱類型可用性用途
.FallbackSubjectstring總是默認主題行。見下文。
.Subjectstring僅在正文中解析後的 主題
.Bodystring總是問題、拉取請求或評論的消息,從 Markdown 解析為 HTML 並進行了清理。不要與 郵件正文 混淆。
.Linkstring總是發起問題、拉取請求或評論的地址。
.Issuemodels.Issue總是發起通知的問題(或拉取請求)。要獲取特定於拉取請求的數據(例如 HasMerged),可以使用 .Issue.PullRequest,但應注意,如果問題不是拉取請求,則此字段將為 nil
.Commentmodels.Comment如果適用如果通知來自添加到問題或拉取請求的評論,這將包含有關評論的信息。
.IsPullbool總是如果郵件通知與拉取請求相關聯(即 .Issue.PullRequest 不是 nil),則為 true
.Repostring總是包括所有者名稱的存儲庫名稱(例如 mike/stuff
.Usermodels.User總是發起事件的存儲庫所有者。要獲取用戶名(例如 mike),可以使用 .User.Name
.Doermodels.User總是觸發通知事件的操作用戶。要獲取用戶名(例如 rhonda),可以使用 .Doer.Name
.IsMentionbool總是如果此通知僅因為用戶在評論中被提及而生成,而不是訂閱了源,則為 true。如果收件人訂閱了問題或存儲庫,則為 false
.SubjectPrefixstring總是如果通知不是關於創建問題或拉取請求,則為 Re: ;否則為空字符串。
.ActionTypestring總是"issue""pull"。將對應於實際的 操作類型,無論選擇了哪個模板。
.ActionNamestring總是它將是上述操作類型之一(newcomment 等),並將對應於實際的 操作名稱,無論選擇了哪個模板。
.ReviewComments[]models.Comment總是審查中的代碼評論列表。評論文本將在 .RenderedContent 中,引用的代碼將在 .Patch 中。

所有名稱都是區分大小寫的。

模板的 主題 部分

郵件 主題 使用的模板引擎是 golang 的 text/template。 請參閱鏈接的文檔以了解其語法的詳細信息。

主題的構建步驟如下:

  • 根據通知類型和存在的模板選擇模板。
  • 解析並解析模板(例如 {{.Issue.Index}} 轉換為問題或拉取請求的編號)。
  • 所有空格字符(例如 TABLF 等)轉換為普通空格。
  • 刪除所有前導、尾隨和冗餘空格。
  • 字符串被截斷為其前 256 個符文(字符)。

如果最終結果是空字符串, 沒有可用的主題模板(即選擇的模板不包括主題部分),將使用 Gitea 的 內部默認值

內部默認(回退)主題相當於:

{{.SubjectPrefix}}[{{.Repo}}] {{.Issue.Title}} (#{{.Issue.Index}})

例如:Re: [mike/stuff] New color palette (#38)

Gitea 的默認主題也可以在模板 元數據 中找到,作為 .FallbackSubject,即使存在有效的主題模板。

模板的 郵件正文 部分

郵件 正文 使用的模板引擎是 golang 的 html/template。 請參閱鏈接的文檔以了解其語法的詳細信息。

郵件 正文 在郵件主題之後解析,因此有一個額外的 元數據 字段,即實際渲染的主題,考慮所有因素後。

預期結果是 HTML(包括結構元素如 <html><body> 等)。可以通過 <style> 塊、classstyle 屬性進行樣式設置。然而,html/template 會進行一些 自動轉義,應該考慮到。

不支持附件(如圖像或外部樣式表)。但是,也可以引用其他模板,例如提供 <style> 元素的內容。外部模板必須放置在 custom/mail 下,並相對於該目錄引用。例如,custom/mail/styles/base.tmpl 可以使用 {{template styles/base}} 包含。

郵件以 Content-Type: multipart/alternative 發送,因此正文以 HTML 和文本格式發送。後者通過剝離 HTML 標記獲得。

故障排除

郵件的渲染方式直接取決於郵件應用程序的功能。許多郵件客戶端甚至不支持 HTML,因此它們顯示生成的郵件中包含的文本版本。

如果模板渲染失敗,只有在郵件發送時才會注意到。 如果主題模板失敗,將使用默認主題,並且無論渲染成功的部分如何,都將使用 郵件正文

如果有問題,請檢查 Gitea 的日誌 以獲取錯誤消息。

示例

custom/templates/mail/issue/default.tmpl

[{{.Repo}}] @{{.Doer.Name}}
{{if eq .ActionName "new"}}
created
{{else if eq .ActionName "comment"}}
commented on
{{else if eq .ActionName "close"}}
closed
{{else if eq .ActionName "reopen"}}
reopened
{{else}}
updated
{{end}}
{{if eq .ActionType "issue"}}
issue
{{else}}
pull request
{{end}}
#{{.Issue.Index}}: {{.Issue.Title}}
------------
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>{{.Subject}}</title>
</head>

<body>
{{if .IsMention}}
<p>
You are receiving this because @{{.Doer.Name}} mentioned you.
</p>
{{end}}
<p>
<p>
<a href="{{AppUrl}}/{{.Doer.LowerName}}">@{{.Doer.Name}}</a>
{{if not (eq .Doer.FullName "")}}
({{.Doer.FullName}})
{{end}}
{{if eq .ActionName "new"}}
created
{{else if eq .ActionName "close"}}
closed
{{else if eq .ActionName "reopen"}}
reopened
{{else}}
updated
{{end}}
<a href="{{.Link}}">{{.Repo}}#{{.Issue.Index}}</a>.
</p>
{{if not (eq .Body "")}}
<h3>Message content</h3>
<hr>
{{.Body}}
{{end}}
</p>
<hr>
<p>
<a href="{{.Link}}">View it on Gitea</a>.
</p>
</body>
</html>

此模板生成如下內容:

主題

[mike/stuff] @rhonda commented on pull request #38: New color palette

郵件正文

@rhonda (Rhonda Myers) updated mike/stuff#38.

Message content

_********_********

Mike, I think we should tone down the blues a little. _********_********

View it on Gitea.

高級

模板系統包含幾個函數,可用於進一步處理和格式化消息。以下是其中一些的列表:

名稱參數可用性用途
AppUrl-任何Gitea 的 URL
AppName-任何app.ini 設置,通常為 "Gitea"
AppDomain-任何Gitea 的主機名
EllipsisStringstring, int任何將字符串截斷為指定長度;根據需要添加省略號
SanitizeHTMLstring僅正文通過刪除任何危險的 HTML 標籤來清理文本
SafeHTMLstring僅正文將輸入作為 HTML,可以用於輸出原始 HTML 內容

這些是 函數,而不是元數據,因此必須這樣使用:

像這樣:{{SanitizeHTML "Escape<my
>text"}} 或這樣:{{ "Escape<my
>text" | SanitizeHTML}} 或這樣:{{AppUrl}} 但不能這樣: {{.AppUrl}}</my
></my
>