模板编写
校对日期:2026-11-16。适用于社区版及全部商业版。
本文面向主题开发者,说明主题模板怎样写:FreeMarker 语法与转义、全局变量与 CMS 指令、页面清单与页面设置、布局变体、 主题设置,以及怎样预览单个模板、排查运行时的模板错误。主题的组成、目录结构和主题清单见主题开发。
一、FreeMarker 模板基础
UJCMS 使用 FreeMarker 方括号标签语法。常用写法如下:
[#assign pageTitle = site.title/]
[#if user??]
<span>${user.username}</span>
[#else]
<a href="${def}/login">登录</a>
[/#if]
[#list channelList as item]
<a href="${item.url}">${item.name}</a>
[/#list]常用的空值处理:
${article.subtitle!''} [#-- 不存在时使用空字符串 --]
[#if article.image?has_content]...[/#if]
[#if article.author??]...[/#if]
${article.views?c} [#-- 数字按机器格式输出 --]数字默认不带千分位(${1234567} 输出 1234567)。写进地址、脚本的 ID 仍建议加 ?c;要显示千分位写 ${article.。
1.1 主布局
推荐在 layout/ 中定义布局宏,在每个页面中使用 include 引入。include 会在 调用方命名空间执行,使页面变量和布局内定义的宏保持可见;如果将默认主题中的 include 改为 import, 变量的可见范围也会变化。
layout/:
[#macro layout title='']
[#escape x as (x)!?html]
<!doctype html>
<html lang="${site.langTag}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>[#if title?has_content]${title}[#else]${site.title}[/#if]</title>
[#include '../snippets/css.html'/]
</head>
<body>
<main>[#nested/]</main>
[#include '../snippets/js.html'/]
</body>
</html>
[/#escape]
[/#macro]templates/:
[#include '../layout/theme.html'/]
[#escape x as (x)!?html]
[@layout title=site.title]
<h1>${site.name}</h1>
[@ArticleList limit='10' orderBy='publishDate_desc'; articles]
[#if articles?size == 0]
<p>暂无内容</p>
[#else]
<ul>
[#list articles as item]
<li><a href="${item.url}">${item.title}</a></li>
[/#list]
</ul>
[/#if]
[/@ArticleList]
[/@layout]
[/#escape]1.2 每个文件都要明确转义
UJCMS 当前没有全局开启 FreeMarker 输出格式自动转义。凡是包含 ${...} 的模板或片段,均应 在该文件内部使用:
[#escape x as (x)!?html]
<h1>${article.title}</h1>
[/#escape]#escape 是词法作用域,调用文件的转义块不会自动覆盖被 include 的文件。因此 header.html、footer.html、分页片段和每个面板片段都应独立声明转义。
仅对规范明确标记为后端已净化的富文本字段使用原样输出,例如文章正文:
[#escape x as (x)!?html]
<article>[#noescape]${article.text!}[/#noescape]</article>
[/#escape]不要对标题、查询参数、会员资料或普通自定义字段使用 #noescape。在本项目的 [#escape] 约定下,优先使用上面的 [#noescape].,不要将 ?no_esc 当成通用替代品。
1.3 常用全局变量
| 变量 | 说明 |
|---|---|
site | 当前站点 |
config | 系统与站点配置 |
user | 当前登录会员,匿名时为空 |
defaultSite | 默认站点 |
Params | 当前请求查询参数 |
page、pageSize | 分页上下文 |
dy | 当前站点动态 URL 前缀 |
api | REST API 前缀 |
ctx | Servlet 上下文路径 |
def | 默认站点/会员相关 URL 前缀 |
assets | 当前主题 assets/ 的公开 URL 前缀 |
v | 静态资源缓存版本 |
_csrf | CSRF 字段、Token 和请求头名称 |
csp_nonce | 内联脚本所需的 CSP nonce |
theme.config | 当前主题的全局设置值 |
pageConfig | 当前页面设置与活动变体设置的合并值 |
channel、article、topic、tag、formType 等业务对象只在相应页面存在。它们的字段与公开 API (/api/article、/api/channel 等)返回的 JSON 一致,开启 SpringDoc 后可在 /swagger-ui/ 查看完整字段, 也可直接参考默认主题各页面模板中的真实用法。
URL 使用建议:
- 站点首页使用
${site.url}。 - 栏目、文章、专题等实体链接优先使用对象自身的
${item.url}。 - 搜索、登录等动态路由使用
${dy}或${def},参照默认主题现有页面。 - 接口请求使用
${api}。 - 不要在主题中写死部署域名、Servlet 上下文或
/themes/1/...。
1.4 使用 CMS 指令取数
指令通常使用“参数 + 循环变量”的形式:
[@ArticlePage
channelId=channel.id
isIncludeSubChannel='true'
orderBy='publishDate_desc'; pagedList]
[#list pagedList.content as item]
<a href="${item.url}">${item.title}</a>
[/#list]
[#include '../snippets/page.html'/]
[/@ArticlePage]常用指令包括 ArticleList、ArticlePage、Article、ArticleNext、ArticlePrev、 Channel、ChannelList、TagList、BlockItemList,以及链接组指令 LinkGroupList(按 slot 取清单 linkSlots 所声明展示位下的链接组)与 LinkList(按 groupId / groupAlias 取组内链接; 参考主题 snippets/ 的页脚友情链接即此写法)等。每个指令都对应一个公开 API 接口(如 ArticleList 对应 GET /,ChannelList 对应 GET /):参数名与接口的查询参数一致,采用 camelCase (如 channel、isIncludeSubChannel、limit、orderBy,写成下划线形式不会生效),返回结构与接口返回的 JSON 一致。 以 API 文档及默认主题中的真实调用为准。
文章类指令与接口只给出访客看得到的文章:
status参数不给或留空(status='')都按"已发布"处理,不会放出草稿、待审核等未公开的文章;要同时列出已归档的文章,写status='0,1'。- 公开接口
GET /不带api/ article limit时返回 20 条;模板指令ArticleList的默认条数不受影响。 - 按关键词查找(
q查标题与正文,text只查正文)走全文索引,按分词匹配,一次最多匹配 500 篇。 查询条件不能直接作用于正文:Q_Contains_这类写法会返回 400。@articleExt-text - 文章列表、分页、全文检索(
ArticleList、ArticlePage、EsArticleList、EsArticlePage、ArticleRelatedList、ArticleTopicList及对应接口)只列出访问者能浏览的栏目里的文章;生成静态页时按游客组。 - 文章详情、上一篇、下一篇都会核对栏目的浏览权限;没有权限时详情返回 401 / 403,上一篇、下一篇为空。 未公开的文章对访客返回 404。浏览计数、顶、踩同样只对访客看得到的文章生效。
专题指令 Topic、TopicList、TopicPage、ArticleTopicList 与专题页面(/topic、/topic/{别名})自标准版起提供。 专题页模板(topic、topics)只在标准版渲染,可直接调用;首页、栏目页等共享模板或侧栏面板调用这些指令时,须置于 [#if config. 内(参考主题 snippets/),否则社区版渲染时会因指令 不存在而报错。
按别名或 ID 查询时,可能找不到对应数据。主题应为列表为空、图片缺失、引用失效或权限不足等情况提供适当的提示或替代内容。
1.5 JavaScript、CSRF 与 CSP
外部脚本通过 ${assets} 引入:
[#escape x as (x)!?html]
<script src="${assets}/js/theme.js?v=${v}" defer></script>
[/#escape]确实需要内联脚本时必须携带 nonce:
<script nonce="${csp_nonce!''}">
window.themeApi = '${api}';
</script>提交表单或调用写接口时,使用 _csrf.、_csrf.token 或 _csrf.,不要关闭 CSRF,也不要把 Token 写入可长期缓存的静态文件。
1.6 固定链接与别名
栏目、专题和文章都有一个别名(URL 中使用的 slug:只允许字母、数字、- 和 _,同一站点内唯一)。 栏目页地址为 /channel/{别名},专题页为 /topic/{别名}(标准版起),分页在其后追加 /{页码}。文章页地址由 「站点设置 → 固定链接」决定,共三种形式:
| 形式 | 文章地址 | 说明 |
|---|---|---|
| ID | /article/{id} | 纯数字,与旧版本一致 |
| ID + 别名(默认) | /article/ | ID 保证唯一,别名提供可读性;未设别名时退化为 /article/{id} |
| 别名 | /article/{别名} | 最短、最可读;未设别名时同样退化为 /article/{id} |
- 别名留空即自动生成:优先由标题转成英文 slug;站点开启中文转拼音后,中文标题会转为拼音; 否则使用 ID。自动生成的别名不会随标题修改而变化,清空后保存可重新生成;手工输入的别名在本站已存在时, 保存会被拒绝。标准版起,文章表单的别名旁提供 AI 生成候选按钮。
- 三种形式的文章地址都能访问:非当前形式的地址会 301 跳转到当前形式,因此切换形式不会产生死链。
- 切换固定链接形式后,请执行一次全文重建:搜索索引中保存了页面地址,不重建则搜索结果仍指向旧形式。
- 开启静态化时,文章地址以静态化设置中的文章路径模板为准,占位符为
{channel_slug}、{article_slug}。 - 模板中始终使用
${article.url}、${channel.url}、${topic.url},不要自行拼接地址;取单个栏目或专题时 用[@Channel slug=、'news'; bean]…[/ @Channel] [@Topic slug=;搜索、标签等伪栏目页 可赋值'…'; bean]…[/ @Topic] channelSlug变量供导航高亮(参考主题snippets/比较header. html channelSlug == nav.)。slug
1.7 片段页(/app/<名称>)
templates/ 不绑定栏目或文章,由地址 ${dy}/app/<名称> 直接渲染;名称只能用字母、数字、下划线和连字符,文件不存在返回 404。 可以使用“常用全局变量”一节的全局变量(site、user、Params 等)和全部 CMS 指令,没有 channel、article 等页面对象。响应不缓存(no-store), 适合在静态页或被缓存的页面里用脚本加载因人而异的内容。默认主题有两个:app/user.html 输出页头的登录状态,app/ 供首页“点击加载更多”按地址参数取下一批文章:
[#escape x as (x)!?html]
[@ArticleList channel='news' Q_LT_publishDate_DateTime=Params.lastArticleDate! limit='10' orderBy='publishDate_desc,id_desc'; list]
[#list list as bean]<li><a href="${bean.url}">${bean.title}</a></li>[/#list]
[/@ArticleList]
[/#escape]fetch('${dy}/app/articles?lastArticleDate=' + encodeURIComponent(lastDate))
.then(r => (r.ok ? r.text() : ''))
.then(html => document.getElementById('articleList').insertAdjacentHTML('beforeend', html));片段是独立的模板文件,要自己写 [#escape];用 innerHTML 插入的片段里的 <script> 不会执行。
二、页面清单与页面设置
pages/ 把稳定页面名绑定到一个或多个模板,并声明页面设置和可视化区域。
{
"$schema": "https://www.ujcms.com/schema/composition/page-manifest.schema.json",
"name": "home",
"label": { "zh-CN": "首页", "en": "Home" },
"order": 10,
"template": "index",
"route": "/",
"slots": {
"main": {
"kind": "region",
"label": { "zh-CN": "主区域", "en": "Main" },
"allowedShapes": ["Notice"],
"allowedRowLayouts": ["full", "halves"],
"constraints": {
"maxRows": 10,
"maxPanelsPerColumn": 4
}
}
}
}注意:
name是页面稳定标识;template是不带目录和扩展名的模板名。template是精确绑定,同一个主题中一个模板最多由一个页面清单绑定。route是文档和预览元数据,不参与运行时模板匹配;“设计 → 模板”和主题详情的预览按钮以它作为固定路由页的 预览地址(见“预览单个模板”一节)。slots当前只允许kind: "region";旧版经典插槽已不再使用。- 页面可只声明
settings而不声明区域。 allowedShapes中的每个组件都必须能在当前主题的shapes/中解析。
页面设置与全局主题设置使用相同的 groups → fields 结构。模板读取 ${pageConfig.。当前页面同时使用布局变体设置时,变体字段覆盖同名页面字段。 为兼容未声明设置的页面,应提供默认值:
[#if (pageConfig.listing.showSummary)!true]
<p>${article.description!''}</p>
[/#if]页面清单的字段和结构以以下文件为准: page-manifest.schema.json。
三、布局变体
当栏目、文章或专题需要多种模板时,在 theme. 中声明 layoutVariants:
{
"layoutVariants": {
"channel": [
{
"value": "default",
"label": { "zh-CN": "默认列表", "en": "Default list" },
"template": "channel"
},
{
"value": "video",
"label": { "zh-CN": "视频网格", "en": "Video grid" },
"template": "channel_video",
"settings": {
"groups": [
{
"name": "listing",
"label": { "zh-CN": "列表展示" },
"fields": {
"columns": {
"type": "enum",
"values": ["2", "3", "4"],
"default": "3",
"label": { "zh-CN": "每行数量" }
}
}
}
]
}
}
]
}
}开发要求:
value是长期使用的变体标识。发布后如需改名,应同时迁移已有数据。template必须对应templates/。<name>. html - 栏目变体只处理栏目页,文章和专题分别放在
article、topic下。 - 变体设置通过
pageConfig读取,不创建另一套模板变量。 - 删除或改名变体前,要考虑已选择该变体的内容和主题更新兼容性。
四、主题设置
全局主题设置声明在 theme.,后台保存值后通过 ${theme. 注入模板:
[#escape x as (x)!?html]
[#assign company = (theme.config.footer.company)!site.name/]
<p data-ujcms-setting="footer.company">${company}</p>
[/#escape]data-ujcms-setting 是可选的构建器约定。预览编辑模式下,它允许管理员点击页面元素直接打开 对应的主题设置;生产页面不会因为该属性改变行为。
设置设计原则:
- 只提供适合管理员长期维护的展示参数,不要把结构性代码变成大量开关。
- 为每个字段设置合理默认值,保证新安装未保存设置时也能渲染。
- 使用清晰稳定的组名和字段名;发布后改名会导致原有设置值无法读取。
- 设置是公开页面展示数据,不应存放密码、Token、私钥或后台连接信息。
- 默认值中的 URL 不会执行
{{theme}}或{{asset:...}}展开;需要主题资源时由模板用${assets}组合。
五、预览单个模板
“设计 → 模板”里,templates/ 目录直下的每个 .html 文件都有“预览”按钮(子目录和原始目录模式没有)。 按钮不读取模板文件本身,而是向后端询问“哪个前台地址会渲染这个模板”,然后在新标签页打开找到的第一个 地址;所选主题不是当前激活主题时,以 ?_theme= 试看方式用所选主题渲染。一个模板能否预览,取决于下面 四个来源能否给出地址,按顺序命中即止:
- 页面清单绑定。激活主题的
pages/以*. manifest. json template绑定了该模板时:清单声明了不带参数的route(如首页的/),就用这个路由;没有route,就在站点的栏目、文章、专题中找“有效模板恰好是它” 的记录(显式选择 > 变体绑定 > 默认),打开该记录的动态地址。所以channel_预览的是真正用它 渲染的那个栏目。video. html - 内置固定路由表。不需要清单的系统页:搜索、标签、投票、RSS、留言板及其发表页、登录、注册、找回密码、 个人中心各页(所有版本);表单类型页、问卷页、专题列表页、第三方登录注册页(标准版起);依申请公开、 领导信箱、在线访谈各页(旗舰版)。表项与渲染它的控制器同径:版本不够或功能未启用的页面不给出地址。
- 实例页来源。以某条记录为上下文的页面:标签详情、投票详情与结果、留言详情、会员主页(所有版本), 问卷详情与结果、表单提交页(标准版起),信件详情、访谈详情(旗舰版)。取站点内第一条前台可见的记录 (已启用、已发布、已审核公开);会员主页以当前管理员本人为代表。
- 表单类型引用。某个开启了“前台可浏览”的表单类型以该模板为“表单列表模板”时,给出
/form-list/;以它为“表单详情模板”时, 给出该类型最新一条表单的{类型ID} /form-item/,类型下没有表单就没有地址(标准版起)。{表单ID}
需要会员登录的页面(个人中心各页、登录后才能填写的表单)会以当前管理员的预览身份打开,页面按管理员本人的 数据渲染,提示语会说明这一点。
点“预览”后若提示无法预览,提示语已说明原因,对应的处理办法如下:
| 提示 | 含义 | 处理 |
|---|---|---|
| 站点暂无可用于预览该模板的…… | 页面可以渲染,但站点里没有使用该模板的内容 | 新建一个栏目 / 文章 / 专题并在其“模板”中选用该模板;或启用一条投票 / 问卷、审核并公开一条留言、选登一封信件、发布一场访谈 |
| 该模板对应的页面由更高版本提供 | 当前版本没有渲染该页面的前台控制器 | 升级版本;低版本可忽略这些模板文件 |
| 该模板所属功能「……」未启用 | 注册、留言板、依申请公开、领导信箱或在线访谈的开关关闭 | 在全局设置(注册)或站点设置中启用该功能 |
| 没有页面渲染该模板 | 四个来源都不认识这个模板名 | 见下文“让自定义模板可预览” |
让自定义模板可预览。 新增一个模板文件不会自动获得预览地址,因为地址来自页面而不是文件:
- 栏目 / 文章 / 专题的新变体模板:文件名沿用
channel_*/article_*/topic_*前缀,把模板名加进对应页面 清单的template列表,再让至少一条内容在“模板”里选用它。 - 已有固定路由的系统页:如果主题把它纳入了页面清单(例如为它声明区域),可同时写上
route,预览就直接用这个 路由,不再依赖内置表。 - 表单页面:文件名沿用
form_list_*/form_item_*,在表单类型里选它作表单列表模板或表单详情模板(该类型须开启“前台可浏览”),见自定义表单。 - 片段、布局、邮件正文等不是页面的文件不会也不需要预览,请放在
snippets/或layout/下,templates/只放页面模板。
清单绑定看的是当前站点激活主题的清单:浏览未激活的主题时,候选地址仍按激活主题的绑定选出,再以 ?_theme= 用所选主题渲染。
六、运行时模板错误与错误编号
模板在运行时出错(变量为空、指令参数错误、include 路径错误等)时,页面上显示什么由查看者身份决定, 与运行环境、application-*. 都无关:
- 匿名访客只看到通用错误页,页上有一个 8 位错误编号(如
3f9a0c12)。访客反馈问题时请让其提供该编号。 - 已登录的后台操作员在页面原位看到带同一编号的黄底错误框(模板路径、行列、出错表达式、FTL 调用栈), 页面其余部分继续渲染,一次就能看到整页的全部错误。身份有三种来源:以后台账号登录前台(勾选“记住我”后 长期有效);从控制台“设计 › 模板管理”点击“预览”(预览链接自带 5 分钟有效的预览身份,活动主题亦然); 控制台 API 的错误响应(随登录令牌)。
- 服务器日志每个错误记一条 ERROR(编号、站点、模板位置、请求路径、错误信息),Tomcat 另记完整堆栈。 Docker 部署看
docker logs,jar 部署看标准输出或你自己配置的日志文件。 - 控制台“设计 › 模板管理 › 最近错误”列出本进程最近 100 条模板错误(时间、编号、模板、位置、请求路径、 错误信息),按当前站点过滤,重启后清空。向技术支持反馈时,把这里的记录或错误编号一并提供即可定位。
模板中途出错不会再发出半截的 200 页面:整页先渲染再输出,失败即换成 500 错误页。静态页生成出错也不会留下 半截文件,错误信息记在“系统 › 生成管理”的任务详情里。
本机开发无需再改配置:以后台账号登录前台一次,之后所有页面都在原位显示错误框。
七、常见问题
页面报 FreeMarker 解析错误
先运行 ThemeTemplateParseTest,然后检查方括号指令是否成对、宏结束标签是否正确、字符串引号 是否闭合。include 文件存在但路径错误通常只会在真实渲染时暴露,也要访问对应页面验证。
页面只显示“出错了”和一个错误编号
这是匿名访客看到的通用错误页。以后台账号登录前台,或从“模板管理”点“预览”,同一页面会在原位显示带该编号的 错误框;也可以到“模板管理 › 最近错误”按编号查看,或在服务器日志中搜索该编号(见“运行时模板错误与错误编号”一节)。
页面显示 ${...} 原文
通常表示该文件没有按 FreeMarker 模板解析、模板路径选错,或把模板表达式写进了静态资源文件。 确认文件位于 templates/、layout/ 或 snippets/,扩展名为 .html。
文章正文显示出 <p> 等 HTML 标签
正文被 [#escape] 转义了。正文和“富文本编辑器”类型的自定义字段保存时已由系统过滤,用 [#noescape]${article. 输出(见“每个文件都要明确转义”一节);其它字段不要这样写。
主题设置保存了但模板没有变化
全局设置读取 theme.config,页面和活动变体设置读取 pageConfig。同时确认字段已在相应 Schema 中声明、组名和字段名大小写一致,并为不存在值的情况提供默认值。
模板列表的“预览”提示无法预览
预览地址来自渲染该模板的页面,而不是模板文件本身,所以新建的文件、片段和布局没有预览地址。提示语已说明 原因:缺内容就先创建使用该模板的内容,功能未启用就先启用,版本不够的页面可忽略,“没有页面渲染该模板”则 按“预览单个模板”一节中“让自定义模板可预览”的说明处理。