🧩 公共标签(通用辅助标签)

最后更新: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.html 的 </body> 之前 -->
{{if .PageJSONLD}}{{.PageJSONLD}}{{end}}
{{if .BreadcrumbJSONLD}}{{.BreadcrumbJSONLD}}{{end}}

{{.PageJSONLD}} 在文章 / 产品 / 案例 / 单页详情页自动生成 Product 或 Article 类型 JSON-LD;{{.BreadcrumbJSONLD}} 生成 BreadcrumbList。两者已是 safeHTML,**直接输出即可,不要再加 safeHTML,也不要手动包 `

本网站使用 Cookie 以保障基本功能与改善体验。详情见隐私政策。