🧩 公共标签(通用辅助标签)
最后更新:2026-11-04
本章汇总所有前台模板都能用的通用标签与函数(公共标签),不限于某个内容类型。Gitl.cn CMS 基于 Go 标准 html/template 引擎,公共能力以「模板函数 + 全局变量」两种形式提供。
📊 公共标签能力总览
以下能力在所有前台模板均可使用,按使用频率从高到低排列。
| 能力 | 用法 | 说明 |
|---|---|---|
| 模板局部复用 | {{template "header.html" .}} |
用 Go 命名模板复用公共片段(见「模板嵌套」) |
| 时间格式化 | {{.CreatedAt \| formatDate "Y-m-d"}} |
支持 Y-m-d / Y/m/d / Y年m月d日(仅日期) |
| 内容截取 | {{.Summary \| truncate 50}} |
按字符(rune)截取,中文友好,超出补 ... |
| 原样输出 HTML | {{.Content \| safeHTML}} |
富文本字段默认转义,标记为安全 HTML 后原样渲染 |
| 数值运算 | {{add .CurrentPage 1}} |
整数相加,用于序号、偏移 |
| JSON/多值拆分 | {{range splitJSON .Images}} |
多图、tags 等多值字段解析为可遍历切片 |
| 自定义片段 | {{.FooterNotice}} |
后台「模板内容片段」以同名全局变量注入 |
| 面包屑 | .ParentCategory / .CategoryName |
栏目页自带父级与当前栏目数据 |
| 当前网址 | {{.SiteDomain}} / {{.URL}} |
站点域名 / 内容详情链接({{.URL}} 的形态由后台「配置参数 → URL规则」决定,详见下方「由后台配置参数控制的输出」) |
| 站点地图与 SEO 文件 | /sitemap.xml、/llms.txt 等 |
运行时自动生成,大数据自动分片 |
| 图片显示尺寸 | CSS 控制 | 原图不变,显示尺寸由 CSS 决定 |
🔧 公共模板函数
以下函数任何前台模板均可调用,语法为 {{管道 | 函数 参数}} 或 {{函数 参数}}。
🕒 formatDate — 时间格式化
| format 取值 | 输出示例 | 说明 |
|---|---|---|
Y-m-d |
2026-08-19 | 默认,横线分隔 |
Y/m/d |
2026/08/19 | 斜杠分隔 |
Y年m月d日 |
2026年08月19日 | 中文格式 |
<time>{{.CreatedAt | formatDate "Y-m-d"}}</time>
<!-- 列表条目 → -->
{{range .Posts}}
<span>{{.CreatedAt | formatDate "Y年m月d日"}}</span>
{{end}}
仅处理日期部分;字段为空 / 非字符串 / 长度不足时返回空(nil 安全,不会 500)。若字符串长度足够但不匹配上述三种格式,则原样返回该字符串(同样不会 500)。需要「时分秒」请用 .CreatedAt 原样输出。
✂️ truncate — 内容截取(中文友好)
按字符数(rune)截取,避免中英文长度不一;超出在末尾补 ...。
{{.Summary | truncate 50}}
<!-- 产品简介截取 30 字 -->
<p>{{.Product.Description | truncate 30}}</p>
🧱 safeHTML — 原样输出 HTML
字段里若含 HTML(如后台富文本),默认会被转义;用 safeHTML 可原样渲染(标记为安全 HTML 后输出)。
<div class="rich">{{.Content | safeHTML}}</div>
📐 add — 数值相加
整数相加,可用于序号、偏移等。
<span>第 {{add .CurrentPage 1}} 页</span>
🔣 splitJSON — JSON/多值数组转列表
把数据库里的 JSON 数组字符串(如多图 .Images)解析为可 range 的切片;非 JSON 时按行拆分。
{{range splitJSON .Images}}
<img src="{{.}}" alt="">
{{end}}
🧩 模板嵌套(局部复用)
Gitl.cn CMS 使用 Go 命名模板做公共片段复用:把公共片段写成 {{define "名字"}}…{{end}},在需要处用 {{template "名字" .}} 引入,. 为传入的数据根。
<!-- header.html 顶部 -->
{{template "header.html" .}}
<!-- 页脚 -->
{{template "footer.html" .}}
<!-- 内置图标片段(default 模板已定义)-->
<div class="icon">{{template "icon-arrow-right"}}</div>
templates// 下的 header.html、footer.html 等即为可被任意页面引入的公共局部。
🌐 全局变量(任意页面可直接读)
除各章节字段外,以下变量在前台模板可用。注意:CanonicalURL / PageJSONLD / BreadcrumbJSONLD 仅在详情页 / 栏目页注入(首页、列表页、搜索页为空),其余为全站可用。
| 变量 | 含义 |
|---|---|
{{.SiteDomain}} |
站点域名(含协议,如 https://www.gitl.cn) |
{{.SiteTitle}} / {{.SiteSubtitle}} |
站点标题 / 副标题 |
{{.SitePrefix}} |
多语言路径前缀(默认站为空,英文站为 /en) |
{{.SiteHomeURL}} / {{.SiteContactURL}} / {{.SiteAboutURL}} |
首页 / 联系我们 / 关于我们 链接 |
{{.CompanyName}} / {{.CompanyPhone}} / {{.CompanyEmail}} … |
公司信息(详见「公司信息」章节) |
{{.Navigations}} / {{.TopCategories}} / {{.ProductCategories}} |
导航菜单 / 顶级栏目 / 产品栏目 |
{{.CurrentYear}} |
当前年份(页脚版权常用) |
{{.LangSwitcher}} |
多语言切换数据(多站点时) |
{{.CanonicalURL}} |
当前页绝对规范地址(详情页 / 栏目页可用;首页、列表页为空) |
{{.OGLocale}} |
Open Graph 语言区域(如 zh_CN / en_US / ja_JP),用于 og:locale NEW |
{{.OGImage}} |
Open Graph 分享图(绝对 URL,系统自动补全域名;无正文图时用站点默认图)NEW |
{{.PageJSONLD}} |
详情页结构化数据(Product / Article,已是 safeHTML;仅详情页有)NEW |
{{.BreadcrumbJSONLD}} |
面包屑结构化数据(BreadcrumbList,已是 safeHTML;仅栏目页 / 详情页有)NEW |
<a href="{{.SiteDomain}}">{{.SiteTitle}}</a>
<p>© {{.CurrentYear}} {{.CompanyName}}</p>
<a href="{{.SiteContactURL}}">联系我们</a>
📈 SEO 头部标签(canonical / hreflang / OG / JSON-LD)
以下为生产模板实际使用的 SEO 头部写法,可直接套用到自己的 header.html / footer.html。所有变量均由 Go 后台自动注入,无需手写 URL。
🔗 中的 canonical / hreflang / OG
<!-- canonical:绝对地址,自动带站点前缀(/en 等) -->
<link rel="canonical" href="{{.CanonicalURL}}">
<!-- hreflang:多语言互链(仅多站点时非空) -->
{{range .HrefLangs}}<link rel="alternate" hreflang="{{.Lang}}" href="{{.Href}}">
{{end}}
<!-- Open Graph -->
<meta property="og:type" content="website">
<meta property="og:url" content="{{.CanonicalURL}}">
<meta property="og:locale" content="{{.OGLocale}}">
<meta property="og:image" content="{{.OGImage}}">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
{{.CanonicalURL}} 已是绝对地址且自动包含多语言前缀;{{.OGLocale}} 输出 zh_CN / en_US 等;{{.OGImage}} 已是绝对 URL(后台「站点 OG 图」或默认占位图),不要再拼域名。
🧱 详情页结构化数据(footer 的 之前输出)
<!-- 放在 footer.html 的 </body> 之前 -->
{{if .PageJSONLD}}{{.PageJSONLD}}{{end}}
{{if .BreadcrumbJSONLD}}{{.BreadcrumbJSONLD}}{{end}}
{{.PageJSONLD}} 在文章 / 产品 / 案例 / 单页详情页自动生成 Product 或 Article 类型 JSON-LD;{{.BreadcrumbJSONLD}} 生成 BreadcrumbList。两者已是 safeHTML,**直接输出即可,不要再加 safeHTML,也不要手动包 `
云建站 SaaS