模板与渲染

相关源文件

• models/activities/action.go
• models/activities/action_list.go
• models/activities/action_test.go
• models/activities/user_heatmap.go
• models/migrations/v1_24/v317.go
• modules/markup/html.go
• modules/markup/html_internal_test.go
• modules/markup/html_link.go
• modules/markup/html_test.go
• modules/markup/markdown/ast.go
• modules/markup/markdown/convertyaml.go
• modules/markup/markdown/goldmark.go
• modules/markup/markdown/markdown.go
• modules/markup/markdown/markdown_test.go
• modules/markup/markdown/meta.go
• modules/markup/markdown/meta_test.go
• modules/markup/markdown/renderconfig.go
• modules/markup/markdown/renderconfig_test.go
• modules/markup/render.go
• modules/markup/renderer.go
• modules/markup/sanitizer.go
• modules/paginator/paginator.go
• modules/paginator/paginator_test.go
• modules/templates/helper.go
• modules/templates/util_render.go
• modules/templates/util_render_test.go
• routers/web/admin/repos.go
• routers/web/explore/repo.go
• routers/web/feed/convert.go
• routers/web/org/home.go
• routers/web/shared/user/header.go
• routers/web/user/notification.go
• routers/web/user/profile.go
• services/context/pagination.go
• services/context/user.go
• services/feed/feed.go
• services/feed/feed_test.go
• services/feed/notifier.go
• templates/base/footer.tmpl
• templates/base/head.tmpl
• templates/base/paginate.tmpl
• templates/org/home.tmpl
• templates/org/menu.tmpl
• templates/repo/header.tmpl
• templates/repo/release_tag_header.tmpl
• templates/status/404.tmpl
• templates/status/500.tmpl
• templates/user/dashboard/dashboard.tmpl
• templates/user/dashboard/feeds.tmpl
• templates/user/notification/notification_div.tmpl
• templates/user/notification/notification_subscriptions.tmpl
• templates/user/overview/header.tmpl
• templates/user/profile.tmpl
• web_src/css/markup/content.css

本文档解释了 Gitea 中使用的模板和渲染系统。它涵盖了模板的组织方式、内容的渲染方式（特别是 markdown），以及渲染流程如何工作。有关模板的国际化和本地化信息，请参阅 配置和国际化。

模板系统概述

Gitea 使用 Go 的 HTML 模板引擎来渲染其 Web 界面。模板系统包括

1. 存储在 templates/ 目录中的模板文件（.tmpl）
2. 在 modules/templates 包中定义的模板辅助函数
3. 将数据传递给模板的渲染上下文
4. 用于用户提供内容的 Markdown 渲染系统

来源：templates/base/head.tmpl templates/base/footer.tmpl templates/repo/header.tmpl templates/user/profile.tmpl templates/org/home.tmpl

模板组织

Gitea 中的模板遵循层级结构

• 基础模板（templates/base/）：定义页面的通用结构
• 部分模板：特定于主要功能，如仓库、用户等。
• 局部模板：在多个模板中包含的可重用组件
• 自定义模板：允许在不更改核心模板的情况下进行自定义

模板文件使用 .tmpl 扩展名，并按功能区域组织。例如，与仓库相关的模板位于 templates/repo/，与用户相关的模板位于 templates/user/ 等。

渲染管道

渲染流程在 Gitea 中处理从初始 HTTP 请求到最终 HTML 响应的所有内容。

来源：modules/markup/markdown/markdown.go147-198 routers/web/user/profile.go38-91 routers/web/org/home.go28-192

上下文准备

每个请求处理程序都会准备一个包含以下内容的上下文：

1. 用户信息（已认证用户）
2. 页面特定数据
3. 请求参数
4. 渲染选项

此上下文将传递给模板并用于渲染。上下文对象定义在 services/context 包中，并由不同的处理程序扩展。

模板选择与渲染

模板根据处理程序进行选择，并使用 Go 的 html/template 包进行渲染。该过程通常遵循：

1. 处理程序准备上下文数据
2. 选择合适的模板
3. 调用 ctx.HTML() 使用准备好的数据渲染模板

来自 user/profile.go 的示例

来源：routers/web/user/profile.go56-91 routers/web/org/home.go49-148

Markdown 渲染

Gitea 渲染系统的一个关键部分是 Markdown 处理，它将用户提供的 Markdown 内容转换为 HTML。

来源：modules/markup/markdown/markdown.go104-146 modules/markup/html.go131-152 modules/markup/sanitizer.go

Markdown 处理组件

Markdown 渲染过程涉及几个关键组件：

1. Goldmark 渲染器：Gitea 使用 Goldmark 库进行 Markdown 渲染，配置在 modules/markup/markdown/markdown.go
2. Markdown 扩展：支持表格、任务列表、语法高亮等。
3. 后处理：对链接、@提及、问题引用等进行额外处理。
4. HTML 清理：安全过滤以防止 XSS 攻击。

渲染上下文

定义在 modules/markup 包中的 RenderContext 携带渲染的重要信息：

• 仓库上下文
• 用户上下文
• URL 信息
• 渲染选项

此上下文在整个渲染流程中传递，并影响内容的处理和显示方式。

来源：modules/markup/markdown/markdown.go58-67 modules/markup/html.go136-152

HTML 后处理

Markdown 转换为 HTML 后，Gitea 会执行几个后处理步骤：

1. 链接处理：将 URL 转换为可点击的链接。
2. @提及：将用户名链接到用户个人资料。
3. 问题引用：将问题编号链接到实际问题。
4. 提交引用：将提交哈希链接到提交页面。
5. 表情符号处理：将表情符号代码转换为表情符号图像或 Unicode 字符。

后处理实现在 modules/markup/html.go 中，使用 PostProcessDefault 函数，该函数将一系列处理器应用于 HTML 内容。

来源：modules/markup/html.go131-152 modules/markup/html_test.go492-528

模板辅助函数

Gitea 提供了一系列丰富的辅助函数供模板使用。这些函数定义在 modules/templates/helper.go 中，并提供诸如以下功能：

• 格式化日期和时间
• 渲染表情符号
• 处理 URL
• 转义 HTML
• 渲染 Markdown 内容

来源：modules/templates/helper.go28-182 templates/repo/header.tmpl modules/templates/util_render.go

常用辅助函数

下表列出了一些常用的模板辅助函数：

功能	目的	示例
SafeHTML	将原始内容渲染为 HTML。	{{SafeHTML .Content}}
HTMLEscape	转义 HTML 特殊字符。	{{HTMLEscape .Title}}
DateUtils.TimeSince	将时间格式化为相对时间。	{{DateUtils.TimeSince .CreatedUnix}}
svg	渲染 SVG 图标。	{{svg "octicon-git-pull-request"}}
AppSubUrl	获取应用程序的基础 URL。	{{AppSubUrl}}/user/login
ctx.Locale.Tr	翻译字符串。	{{ctx.Locale.Tr "repo.issues"}}
QueryBuild	构建查询字符串。	{{QueryBuild "/user/settings" "tab=repos"}}

来源：modules/templates/helper.go29-182 modules/templates/util_render.go36-96

渲染特殊内容

Gitea 为不同类型的内容提供了特殊的渲染功能。

提交信息

提交消息在渲染时会特别处理链接、问题引用和格式。

来源： modules/templates/util_render.go36-52 user/dashboard/feeds.tmpl86-104

问题和拉取请求标题

问题和拉取请求标题以易读性和链接为重点进行渲染

来源： modules/templates/util_render.go227-236 user/notification/notification_div.tmpl54-60

上下文和数据流

Context 对象在 Gitea 的渲染系统中起着至关重要的作用，它将数据传递给各个组件

来源： routers/web/user/profile.go56-91 modules/markup/markdown/markdown.go58-67 modules/markup/html.go241-240

数据传递

1. HTTP 请求 → Context：路由创建基于 HTTP 请求的 Context
2. Context → Handler：Context 被传递给相应的 Handler
3. Handler → Template Data：Handler 准备数据并将其存储在 ctx.Data 中
4. Template Data → Template：Template 使用像 {{.SomeVariable}} 这样的变量来访问数据
5. Content → Render Context：内容渲染使用包含仓库和用户信息 (RenderContext) 的 RenderContext

扩展和定制

Gitea 提供了多种方式来扩展和定制渲染系统

1. 自定义模板：在 custom/templates/ 目录中创建自定义模板
2. 模板变量：使用 ctx.Data 映射注入自定义数据
3. 自定义渲染器：实现 markup.Renderer 接口以支持自定义内容类型

最佳实践

定制模板或扩展渲染系统时

1. 尽可能使用现有的辅助函数
2. 遵循模板组织的既定模式
3. 确保对用户提供的内容进行适当的 HTML 转义
4. 考虑性能影响，特别是对于经常访问的页面

来源： modules/markup/renderer.go14-74 modules/templates/helper.go28-182

渲染内容的 CSS 和样式

Gitea 通过 CSS 类为渲染后的内容应用一致的样式

1. Markup 类：.markup 类应用于渲染内容容器
2. 代码块：带语法高亮的代码块样式
3. 任务列表：复选框和任务列表的特殊样式
4. 表格：一致的表格样式

渲染内容的 CSS 定义在 web_src/css/markup/content.css 中。

来源： web_src/css/markup/content.css1-568

总结

Gitea 中的模板和渲染系统是一个全面的框架，负责

1. 模板管理：按功能区域划分，支持继承和局部视图
2. 内容渲染：Markdown 处理，包含扩展和后处理
3. 辅助函数：为模板提供丰富的实用函数集
4. 安全性：HTML 清理以防止 XSS 攻击

该系统使 Gitea 能够提供一致、功能丰富且安全的 UI，同时保持定制的灵活性。