Documentation
¶
Overview ¶
Package render 负责加载 HTML 模板、注册模板函数,并提供渲染辅助。
Index ¶
- Constants
- Variables
- func CommonFuncMap() template.FuncMap
- func HighlightCodeBlocks(src string) string
- func PostCustomCSS(post any) template.HTML
- func RenderMarkdown(md string) string
- func SanitizeHTML(src string) string
- type Renderer
- func (r *Renderer) ClearPreviewTheme()
- func (r *Renderer) ConfigureTemplateRuntime(providers TemplateProviders)
- func (r *Renderer) FilterPostContent(ctx context.Context, post *model.Post) template.HTML
- func (r *Renderer) FilterPostTitle(ctx context.Context, post *model.Post) string
- func (r *Renderer) HasTemplate(name string) bool
- func (r *Renderer) Hooks() hook.Executor
- func (r *Renderer) Hot() bool
- func (r *Renderer) Instance(name string, data any) ginrender.Render
- func (r *Renderer) LoadPreviewTheme(themeDir, themeName string) error
- func (r *Renderer) LoadThemeTemplates(themeDir string) error
- func (r *Renderer) PreviewInstance(name string, data any, previewName string) ginrender.Render
- func (r *Renderer) ReleaseToHotDir(dir string) error
- func (r *Renderer) Reload() error
- func (r *Renderer) ResetToDefault() error
- func (r *Renderer) ResolveFragment(name string) (string, bool)
- func (r *Renderer) ResolveTemplate(pageType string) string
- func (r *Renderer) ResolveTemplateWithPreview(pageType, previewName string) string
- func (r *Renderer) ResolveTemplateWithPreviewData(pageType, previewName string, data any) string
- func (r *Renderer) SetDefaultThemeFS(fsys fs.FS)
- func (r *Renderer) SetHookInvokeProvider(fn func(ctx *RequestContext, name string, args ...any) any)
- func (r *Renderer) SetThemeWidgetsProvider(fn func(ctx *RequestContext, area string) []WidgetInfo)
- func (r *Renderer) SetWidgetResolver(resolver hook.WidgetResolver)
- func (r *Renderer) Template() *template.Template
- func (r *Renderer) UseFS(fsys fs.FS, hot bool) error
- type RequestContext
- type TemplateProviders
- type TemplateRuntime
- type WidgetInfo
Constants ¶
const ( // ThemeLoaderDataKey 是模板数据中保存当前请求 DataLoader 的内部 key。 // 它不供模板直接使用,仅用于主题模板函数读取请求级数据。 ThemeLoaderDataKey = "__theme_loader" // ThemeDataKey 是模板数据中保存当前请求主题对象的内部 key。 // 它不供模板直接使用,仅用于模板函数复用请求级当前主题,避免重复查询 Setting。 ThemeDataKey = "__theme" // ContextDataKey 是模板数据中保存当前请求 context 的内部 key。 // 前台页面的 Data[ContextDataKey] = c.Request.Context() ContextDataKey = "__request_context" )
Variables ¶
var TemplateHierarchy = map[string][]string{
"index": {"index.gohtml"},
"post": {"post.gohtml", "index.gohtml"},
"page": {"page.gohtml", "post.gohtml", "index.gohtml"},
"category": {"category.gohtml", "list.gohtml", "index.gohtml"},
"tag": {"tag.gohtml", "list.gohtml", "index.gohtml"},
"search": {"search.gohtml", "list.gohtml", "index.gohtml"},
"list": {"list.gohtml", "index.gohtml"},
"archive": {"archive.gohtml", "list.gohtml", "index.gohtml"},
"error": {"error.gohtml"},
}
TemplateHierarchy 定义页面类型到模板文件名的 fallback 链。 主题只需提供链中任一模板即可,系统按顺序查找第一个存在的。
Functions ¶
func CommonFuncMap ¶
CommonFuncMap 返回主题和插件模板共用的基础模板函数。 插件模板解析时复用此函数集,确保插件模板也能使用 post_url、category_url 等函数。
func HighlightCodeBlocks ¶
HighlightCodeBlocks 为 HTML 中的 <pre><code> 做服务端高亮与行号输出。
func PostCustomCSS ¶ added in v0.0.11
PostCustomCSS 输出文章/页面详情页专用 CSS。
func RenderMarkdown ¶
RenderMarkdown 把 Markdown 渲染为 HTML,消毒后复用统一的代码块高亮逻辑。
func SanitizeHTML ¶
SanitizeHTML 清理用户可编辑/导入的正文 HTML,保留常见富文本但移除脚本与事件属性。
Types ¶
type Renderer ¶
type Renderer struct {
// contains filtered or unexported fields
}
Renderer 持有模板配置,既支持静态模板,也支持开发期热更新。 项目启动时会将 Renderer 实例赋值给 gin 引擎的 HTMLRender
- c.HTML(code, name, obj) 时, 会通过 Renderer.Instance 生成一个 [Render] 实例
- 也可以直接获取到 [Render] 后调用 c.Render(code, render)
func (*Renderer) ClearPreviewTheme ¶
func (r *Renderer) ClearPreviewTheme()
ClearPreviewTheme 清除预览主题模板缓存。
func (*Renderer) ConfigureTemplateRuntime ¶
func (r *Renderer) ConfigureTemplateRuntime(providers TemplateProviders)
ConfigureTemplateRuntime 一次性配置主题模板运行时回调(启动时由 BindTemplateFunctions 调用)。
func (*Renderer) FilterPostContent ¶
FilterPostContent 对文章正文 HTML 应用 post.content_html 和 post.footer_html filter 链。 供 Feed 等非模板渲染路径使用,确保表情转换、尾部 HTML 等在 RSS 阅读器中生效。
func (*Renderer) FilterPostTitle ¶
FilterPostTitle 对文章标题文本应用 post.title filter 链。 供 Feed 等非模板渲染路径使用,保持与模板中的 post_title_text 一致。
func (*Renderer) HasTemplate ¶
HasTemplate 检查指定名称的模板是否存在于当前模板集中。
func (*Renderer) Instance ¶
Instance 实现 gin 的 render.HTMLRender 接口。它始终使用当前缓存的模板实例。
func (*Renderer) LoadPreviewTheme ¶
LoadPreviewTheme 加载预览主题的模板到独立缓存,不影响主模板。
func (*Renderer) LoadThemeTemplates ¶
LoadThemeTemplates 加载主题模板目录。先解析主题模板,再补充内置组件模板, 再补充主题自定义组件模板(覆盖内置),最后补充 admin/auth 模板中缺失的。
func (*Renderer) PreviewInstance ¶
PreviewInstance 返回预览主题的模板实例。previewName 需与 LoadPreviewTheme 时一致。 如果预览未激活或名称不匹配,回退到主模板。
func (*Renderer) ReleaseToHotDir ¶
ReleaseToHotDir 把当前模板写入磁盘目录,并切换到该目录的 hot 模式。 这样单二进制启动后也能在后台释放模板文件并启用手动热更新。
func (*Renderer) ResetToDefault ¶
ResetToDefault 重置为默认主题模板 + admin/auth 回退。 优先从磁盘 themes/default/templates/ 加载,不存在时回退 embed。
func (*Renderer) ResolveFragment ¶
ResolveFragment 将 fragment 名(如 "comments")转为模板名(如 "fragment_comments.gohtml"), 并检查该模板是否存在。返回模板名和是否找到。 主题通过定义 fragment_<name>.gohtml 来支持对应 fragment 的局部渲染。
func (*Renderer) ResolveTemplate ¶
ResolveTemplate 根据页面类型查找主题中第一个存在的模板。 如果链中所有模板都不存在,返回链中第一个(让 Go template 报错)。
func (*Renderer) ResolveTemplateWithPreview ¶
ResolveTemplateWithPreview 根据预览主题状态在对应模板集中解析页面类型。
func (*Renderer) ResolveTemplateWithPreviewData ¶
ResolveTemplateWithPreviewData 根据页面类型和当前模板数据解析更细粒度的模板层级。 例如 page-about.gohtml、post-123.gohtml、category-go.gohtml 会优先于通用模板。
func (*Renderer) SetDefaultThemeFS ¶
SetDefaultThemeFS 设置默认主题的 embed 文件系统,用于 ResetToDefault 时从 embed 加载。
func (*Renderer) SetHookInvokeProvider ¶
func (r *Renderer) SetHookInvokeProvider(fn func(ctx *RequestContext, name string, args ...any) any)
SetHookInvokeProvider 更新 hookInvoke 模板函数(主题重载时调用)。
func (*Renderer) SetThemeWidgetsProvider ¶
func (r *Renderer) SetThemeWidgetsProvider(fn func(ctx *RequestContext, area string) []WidgetInfo)
SetThemeWidgetsProvider 更新 renderWidgets 获取区域组件列表的实现。
func (*Renderer) SetWidgetResolver ¶
func (r *Renderer) SetWidgetResolver(resolver hook.WidgetResolver)
SetWidgetResolver 设置统一的组件查找器(启动时由 populateWidgetRegistry 调用)。
type RequestContext ¶
type RequestContext struct {
// Context 是当前 HTTP 请求的 context.Context,从模板 Data 的 __request_context key 提取。
// 用于传递 trace ID、超时控制、请求取消信号等;若 Data 中不存在则 fallback 到 context.Background()。
Context context.Context
// Template 是已 clone 并绑定了请求级模板函数闭包的模板实例。
// 模板函数(如 listComments)通过它执行自定义评论模板等子模板。
Template *template.Template
// Data 是模板渲染的根数据对象(通常是 gin.H),包含所有模板可访问的字段,
// 如 SiteName、Post、Comments、CurrentUser、Menus 等。
Data any
// Runtime 是模板运行时能力提供者,持有 hooks 执行器、组件提供者、
// 主题选项读取器、hook 调用器等回调。之前作为独立参数传递,现已合并进 RequestContext。
Runtime *TemplateRuntime
// ThemeLoader 是当前请求的 DataLoader 实例(any 避免循环依赖 store 包)。
// 模板函数中用于按需加载额外数据(如文章详情、分类列表等)。
ThemeLoader any
// Theme 是当前激活的主题对象(any 避免循环依赖 theme 包)。
// 模板函数中用于读取主题相关配置(如主题选项、组件区域等)。
Theme any
// WidgetOptions 是当前正在渲染的组件的选项键值对。
// render_widgets 遍历组件时设置,widget_option 模板函数读取;渲染完成后清空为 nil。
WidgetOptions map[string]string
}
RequestContext 是一次模板渲染独占的运行时上下文。 类型保持为 any,避免 render 包依赖 store/theme 包。
type TemplateProviders ¶
type TemplateProviders struct {
WidgetsProvider func(ctx *RequestContext, area string) []WidgetInfo
ThemeOption func(ctx *RequestContext, optionID string) string
Hooks hook.Executor
HookInvoke func(ctx *RequestContext, name string, args ...any) any
WidgetResolver hook.WidgetResolver
}
TemplateProviders 集中保存主题模板函数需要回调宿主的能力。
之前这些能力分散在多个 atomic.Pointer + SetXxxProvider 方法中,启动主流程需要理解 “哪个 Manager 给 Renderer 注入哪个函数”。集中成一个对象后,cmd/server/manager 只需要 读成“把模板运行时能力挂到 Renderer 上”,主题作者面对的模板函数也更容易对应到底层能力。
type TemplateRuntime ¶
type TemplateRuntime struct {
// contains filtered or unexported fields
}
TemplateRuntime 保存主题模板函数需要调用的运行时能力。 它归属于 Renderer 实例,避免不同渲染器之间通过包级全局变量串联。
type WidgetInfo ¶
type WidgetInfo struct {
InstanceID string // 组件实例 ID,同一组件重复添加时用于区分实例
ID string // 组件 ID
Source string // builtin / theme / plugin
PluginID string // Source=plugin 时的插件 ID
TemplateName string // 模板 define 名称,如 "widget_search"
Options map[string]string // 组件选项
}
WidgetInfo 是模板渲染阶段需要的组件信息。 放在 render 包里,避免 renderWidgets 为了读取 theme.WidgetInfo 而使用反射。