render

package
v0.0.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 31, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package render 负责加载 HTML 模板、注册模板函数,并提供渲染辅助。

Index

Constants

View Source
const (
	// ThemeLoaderDataKey 是模板数据中保存当前请求 DataLoader 的内部 key。
	// 它不供模板直接使用,仅用于主题模板函数读取请求级数据。
	ThemeLoaderDataKey = "__theme_loader"
	// ThemeDataKey 是模板数据中保存当前请求主题对象的内部 key。
	// 它不供模板直接使用,仅用于模板函数复用请求级当前主题,避免重复查询 Setting。
	ThemeDataKey = "__theme"
	// ContextDataKey 是模板数据中保存当前请求 context 的内部 key。
	// 前台页面的 Data[ContextDataKey] = c.Request.Context()
	ContextDataKey = "__request_context"
)

Variables

View Source
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

func CommonFuncMap() template.FuncMap

CommonFuncMap 返回主题和插件模板共用的基础模板函数。 插件模板解析时复用此函数集,确保插件模板也能使用 post_url、category_url 等函数。

func HighlightCodeBlocks

func HighlightCodeBlocks(src string) string

HighlightCodeBlocks 为 HTML 中的 <pre><code> 做服务端高亮与行号输出。

func PostCustomCSS added in v0.0.11

func PostCustomCSS(post any) template.HTML

PostCustomCSS 输出文章/页面详情页专用 CSS。

func RenderMarkdown

func RenderMarkdown(md string) string

RenderMarkdown 把 Markdown 渲染为 HTML,消毒后复用统一的代码块高亮逻辑。

func SanitizeHTML

func SanitizeHTML(src string) string

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 New

func New(fsys fs.FS) (*Renderer, error)

New 从给定文件系统(通常是 embed.FS 的子目录)加载所有 *.gohtml 模板。

func NewHot

func NewHot(dir string) (*Renderer, error)

NewHot 从磁盘目录创建一个可热更新的模板渲染器。 启动时会先 Parse 一次模板,之后只有显式调用 Reload 才会重新解析。

func (*Renderer) ClearPreviewTheme

func (r *Renderer) ClearPreviewTheme()

ClearPreviewTheme 清除预览主题模板缓存。

func (*Renderer) ConfigureTemplateRuntime

func (r *Renderer) ConfigureTemplateRuntime(providers TemplateProviders)

ConfigureTemplateRuntime 一次性配置主题模板运行时回调(启动时由 BindTemplateFunctions 调用)。

func (*Renderer) FilterPostContent

func (r *Renderer) FilterPostContent(ctx context.Context, post *model.Post) template.HTML

FilterPostContent 对文章正文 HTML 应用 post.content_html 和 post.footer_html filter 链。 供 Feed 等非模板渲染路径使用,确保表情转换、尾部 HTML 等在 RSS 阅读器中生效。

func (*Renderer) FilterPostTitle

func (r *Renderer) FilterPostTitle(ctx context.Context, post *model.Post) string

FilterPostTitle 对文章标题文本应用 post.title filter 链。 供 Feed 等非模板渲染路径使用,保持与模板中的 post_title_text 一致。

func (*Renderer) HasTemplate

func (r *Renderer) HasTemplate(name string) bool

HasTemplate 检查指定名称的模板是否存在于当前模板集中。

func (*Renderer) Hooks

func (r *Renderer) Hooks() hook.Executor

Hooks 返回当前 hook 执行器,供非模板渲染路径(如 Feed)使用。

func (*Renderer) Hot

func (r *Renderer) Hot() bool

Hot 返回当前渲染器是否处于本地模板热更新模式。

func (*Renderer) Instance

func (r *Renderer) Instance(name string, data any) ginrender.Render

Instance 实现 gin 的 render.HTMLRender 接口。它始终使用当前缓存的模板实例。

func (*Renderer) LoadPreviewTheme

func (r *Renderer) LoadPreviewTheme(themeDir, themeName string) error

LoadPreviewTheme 加载预览主题的模板到独立缓存,不影响主模板。

func (*Renderer) LoadThemeTemplates

func (r *Renderer) LoadThemeTemplates(themeDir string) error

LoadThemeTemplates 加载主题模板目录。先解析主题模板,再补充内置组件模板, 再补充主题自定义组件模板(覆盖内置),最后补充 admin/auth 模板中缺失的。

func (*Renderer) PreviewInstance

func (r *Renderer) PreviewInstance(name string, data any, previewName string) ginrender.Render

PreviewInstance 返回预览主题的模板实例。previewName 需与 LoadPreviewTheme 时一致。 如果预览未激活或名称不匹配,回退到主模板。

func (*Renderer) ReleaseToHotDir

func (r *Renderer) ReleaseToHotDir(dir string) error

ReleaseToHotDir 把当前模板写入磁盘目录,并切换到该目录的 hot 模式。 这样单二进制启动后也能在后台释放模板文件并启用手动热更新。

func (*Renderer) Reload

func (r *Renderer) Reload() error

Reload 重新解析模板并替换当前缓存。仅热更新模式支持该操作。

func (*Renderer) ResetToDefault

func (r *Renderer) ResetToDefault() error

ResetToDefault 重置为默认主题模板 + admin/auth 回退。 优先从磁盘 themes/default/templates/ 加载,不存在时回退 embed。

func (*Renderer) ResolveFragment

func (r *Renderer) ResolveFragment(name string) (string, bool)

ResolveFragment 将 fragment 名(如 "comments")转为模板名(如 "fragment_comments.gohtml"), 并检查该模板是否存在。返回模板名和是否找到。 主题通过定义 fragment_<name>.gohtml 来支持对应 fragment 的局部渲染。

func (*Renderer) ResolveTemplate

func (r *Renderer) ResolveTemplate(pageType string) string

ResolveTemplate 根据页面类型查找主题中第一个存在的模板。 如果链中所有模板都不存在,返回链中第一个(让 Go template 报错)。

func (*Renderer) ResolveTemplateWithPreview

func (r *Renderer) ResolveTemplateWithPreview(pageType, previewName string) string

ResolveTemplateWithPreview 根据预览主题状态在对应模板集中解析页面类型。

func (*Renderer) ResolveTemplateWithPreviewData

func (r *Renderer) ResolveTemplateWithPreviewData(pageType, previewName string, data any) string

ResolveTemplateWithPreviewData 根据页面类型和当前模板数据解析更细粒度的模板层级。 例如 page-about.gohtml、post-123.gohtml、category-go.gohtml 会优先于通用模板。

func (*Renderer) SetDefaultThemeFS

func (r *Renderer) SetDefaultThemeFS(fsys fs.FS)

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 调用)。

func (*Renderer) Template

func (r *Renderer) Template() *template.Template

Template 返回当前缓存的底层模板。

func (*Renderer) UseFS

func (r *Renderer) UseFS(fsys fs.FS, hot bool) error

UseFS 切换到指定文件系统重新加载模板,并设置 hot 模式标记。

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 包。

func (*RequestContext) T

func (ctx *RequestContext) T(msg string, args ...any) string

T 从当前请求上下文获取 translator 并翻译,自动 HTML 转义。 用法: ctx.T("msg") 或 ctx.T("msg", args...) xgettext 通过 T:1 关键字自动提取翻译字符串。

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 而使用反射。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL