主题开发
校对日期:2026-11-16。适用于社区版及全部商业版。
适用范围:UJCMS FreeMarker 模板主题,
templateSpecVersion: "2.。0" UJCMS 主题使用 FreeMarker
.html模板。本文以仓库中的 默认主题和运行时 JSON Schema 为准。
本文面向主题设计师、前端开发者和集成商,说明主题由什么组成、开发前要规划什么,以及开发目录、目录结构、主题清单、 静态资源和本地开发环境。主题开发的其余部分分在三篇手册里:
- 模板编写:FreeMarker 模板、全局变量与 CMS 指令、页面清单、布局变体、主题设置、预览单个模板和模板错误。
- 组件、区域与演示数据:可视化构建器使用的组件(Shape)与区域,以及随主题提供的演示数据。
- 主题测试与发布:语法与页面检查、打包、安装、预览、激活、更新和发布验收清单。
第一次制作主题时,建议复制默认主题后按需删减;仅支持少量页面的简单站点也可从空目录开始。
一、先了解主题由什么组成
一个完整的主题包包含以下内容:
- 渲染代码:FreeMarker 页面、主布局和可复用片段。
- 静态资源:编译后的 CSS、JavaScript、图片、字体和必要的前端依赖。
- 主题清单:主题标识、版本、截图、全局设置和栏目/文章/专题布局变体。
- 页面清单:模板与页面的对应关系、页面设置和可视化区域声明。
- 组件定义:可在可视化构建器中添加到区域的组件(Shape),以及对应的面板模板。
- 种子数据(演示数据):可选的页面区域初始布局,以及栏目、文章、区块等演示内容。本文在介绍文件格式和导入机制时使用“种子数据”这一术语。
从设计到发布的推荐流程如下:
- 确定站点页面和内容模型。
- 建立主题目录并填写主题清单。
- 实现主布局、公共片段和页面模板,见模板编写。
- 声明主题设置、页面清单和布局变体。
- 按需实现 Shape、可视化区域和种子数据,见组件、区域与演示数据。
- 构建用于生产环境的静态资源。
- 完成语法、页面、响应式、安全和性能验证,见主题测试与发布。
- 将主题目录的内容打包为 ZIP 文件,上传安装并进行最终验收。
二、开发前的页面与数据规划
编码前先列出主题实际要支持的页面。常见页面包括:
| 页面 | 常用模板名 | 主要上下文 |
|---|---|---|
| 首页 | index | site、文章/栏目查询指令 |
| 栏目页 | channel | channel |
| 文章页 | article | article、channel |
| 专题页(标准版起) | topic | topic |
| 搜索页 | sys_search | Params、搜索指令 |
| 标签页 | sys_tag、sys_tag_item | 标签与文章分页指令 |
| 登录/注册/会员中心 | mem_* | user、表单和 CSRF 上下文 |
| RSS、投票、问卷、留言等 | sys_* | 对应业务对象和指令 |
主题不必复制所有默认主题页面,但站点可能访问的每一种模板都必须存在。缺少被栏目、文章、 专题或系统路由选中的模板时,请求会失败或进入 404。
各模板由下列地址渲染,文件都在 templates/ 下:
| 访问地址 | 模板 |
|---|---|
/ | index |
/channel/{别名} | 栏目的 栏目模板,未选为 channel |
/article/… | 文章的 独立模板 → 所属栏目的 文章模板 → article |
/topic/{别名}、/topic | 专题的 专题模板(未选为 topic)、topics |
/search、/tag、/tag/{id}、/rss | sys_search、sys_tag、sys_tag_item、sys_rss |
/vote、/vote/{id}、/vote/ | sys_vote、sys_vote_show、sys_vote_result |
/message-board、…/create、…/{id} | sys_、sys_、sys_ |
/login、/register、/password-reset、/users/{id} | mem_login、mem_register、mem_、mem_user |
/settings、/settings/{名称} | mem_、mem_ |
/app/{名称} | app/{名称} |
栏目模板、文章模板在 内容 → 栏目管理 的栏目表单里选,文章的独立模板在文章表单里选。下拉框只列出当前主题 templates/ 目录直下、 文件名以 channel(文章为 article,专题为 topic)开头的文件;选“主题默认”即不指定。切换主题后,已选的模板在新主题里 不存在时按默认模板显示,选择本身不会被改写。
设计阶段至少确认以下事项:
- 桌面、平板和手机布局,以及导航折叠方式。
- 首页、栏目、文章等页面的内容层级和空数据状态。
- 栏目和文章是否有多种展示样式,例如视频网格、产品列表、下载详情。
- 哪些文字、颜色、备案信息应允许管理员配置。
- 哪些区域应交给可视化构建器编排。
- 是否随主题提供演示内容,以及卸载主题后这些内容如何处理。
- SEO 标题、描述、Canonical、结构化数据及多语言
hreflang。 - 无障碍要求,包括语义标签、焦点状态、图片替代文字和触控目标大小。
页面行为和可用数据以模板编写的“FreeMarker 模板基础”一节(全局变量、业务对象、CMS 指令)和参考主题 themes/ 中的真实模板为准。 模板拿到的业务对象与公开 API(/api/**)返回的 JSON 一致:在 application. 中开启 springdoc. 与 springdoc. 后,可在 /swagger-ui/ 查看每个对象的字段。不要只根据某一份页面模板猜测字段。
三、建立开发目录
3.1 推荐方式:复制参考主题
本地开发时,主题目录位于:
ujcms-starter/src/main/webapp/themes/{siteId}/{themeName}/例如为站点 1 创建 acme 主题,可从仓库根目录执行:
THEME_SOURCE=ujcms-starter/src/main/webapp/themes/1/default
THEME_TARGET=ujcms-starter/src/main/webapp/themes/1/acme
mkdir -p "$THEME_TARGET"
rsync -a --exclude node_modules "$THEME_SOURCE/" "$THEME_TARGET/"然后至少修改:
theme.中的manifest. json name、themeName、version、作者和说明。- 主题预览图、截图、Logo、配色和文字。
- 不需要的页面、组件、种子及其清单引用。
package.json中的包名,避免与默认主题混淆。
不要直接把默认主题原样改名发布。默认主题包含完整会员、内容变体和演示数据,保留未验证的 功能会扩大维护和测试范围。
3.2 最小主题
安装器要求主题 ZIP 至少有一个位于 templates/ 下的 .html 文件。一个真正可访问的最小 主题通常还需要主布局、静态资源和主题清单:
acme/
├── layout/
│ └── theme.html
├── templates/
│ └── index.html
├── snippets/
│ ├── css.html
│ └── js.html
├── assets/
│ ├── css/style.css
│ └── js/theme.js
├── pages/
│ └── home.manifest.json
├── shapes/
│ └── Notice.json
└── theme.manifest.json最小结构只用于验证安装和首页渲染。实际站点仍需补齐路由会使用的栏目、文章和系统页面。
四、标准目录结构
<theme>/
├── layout/ # 主布局宏
│ └── theme.html
├── templates/ # 可路由的页面模板
│ ├── index.html
│ ├── channel.html
│ ├── article.html
│ └── app/ # /app/<name> 使用的 AJAX HTML 片段页
├── snippets/ # include 片段
│ ├── header.html
│ ├── footer.html
│ └── panels/ # Shape 面板模板,文件名与 Shape.name 一致
├── assets/ # 生产期静态资源
│ ├── css/
│ ├── js/
│ ├── img/
│ └── vendor/
├── pages/ # 页面清单:*.manifest.json
├── shapes/ # 主题自有组件:*.json
├── seed/
│ ├── regions/ # 页面区域初始布局:*.regions.json
│ └── content/ # 可选演示内容和演示媒体
├── thumbnails/ # 可选的构建器组件缩略图
├── _src/ # 可选的 CSS/JS/图标构建源文件
├── preview.svg # 可选主题封面,推荐 16:10
├── package.json # 可选,仅开发期使用
└── theme.manifest.json关键约定:
templates/只放页面模板;主布局和片段分别放在layout/、snippets/。- 新主题静态资源统一放在
assets/,模板通过${assets}引用。 - 浏览器只能直接访问
assets/、thumbnails/里的文件,以及主题目录下的图片(封面、截图);模板、清单、seed/、_src/等其余文件一律返回 404,不会被访客取走。页面要用的样式、脚本、字体放在别处就加载不到, 详见主题安全与部署约束的“主题文件的对外访问范围”一节。 pages/、shapes/、seed/、i18n/内只能放 JSON;唯一例外是seed/,其中可以携带演示图片、视频和附件。content/ assets/ - 主题页面、布局和片段统一使用 FreeMarker
.html文件。 - 每个主题是一个站点自己的实例,运行时通过以下组合唯一标识:
(siteId, themeName)。 - 主题使用到的每个 Shape 都应由主题自身声明,不要假定存在可跨主题使用的核心 Shape。
五、编写 theme.manifest.json
建议所有可分发主题都提供清单。以下是适合作为起点的示例:
{
"$schema": "https://www.ujcms.com/schema/composition/theme-manifest.schema.json",
"name": "Acme 企业主题",
"themeName": "acme",
"version": "1.0.0",
"templateSpecVersion": "2.0",
"kind": "theme",
"author": {
"name": "Acme Studio",
"url": "https://example.com"
},
"description": "适用于企业官网的响应式 FreeMarker 主题。",
"license": "Proprietary",
"preview": "preview.svg",
"screenshots": ["screenshots/home.webp", "screenshots/article.webp"],
"tags": ["企业", "响应式"],
"minUjcmsVersion": "13.0.0",
"settings": {
"groups": [
{
"name": "footer",
"label": { "zh-CN": "页脚", "en": "Footer" },
"fields": {
"company": {
"type": "text",
"default": "Acme 公司",
"label": { "zh-CN": "公司名称", "en": "Company name" }
}
}
}
]
}
}常用字段说明:
| 字段 | 用途 |
|---|---|
name | 控制台显示名称,可使用中文 |
themeName | 稳定的主题标识,建议小写字母、数字和连字符 |
version | 主题版本,使用语义化版本 |
templateSpecVersion | 当前写 2.0 |
kind | 渲染主题写 theme;只含数据的包写 data-only |
license | 主题的许可证标识:开源许可证写 SPDX 标识(如 MIT),自定义协议写 LicenseRef-<名称>-<版本>;协议文本放在主题根目录的 LICENSE 或 LICENSE.md,见主题授权 |
preview | 主题封面相对路径,推荐 16:10 |
screenshots | 详情页截图相对路径列表 |
minUjcmsVersion | 经过实际验证的最低 UJCMS 版本 |
settings | 全局主题设置,模板通过 theme.config.* 读取 |
layoutVariants | 栏目、文章、专题可选择的模板变体 |
seed | 声明随包携带的演示数据类型 |
linkSlots | 主题会渲染的链接组展示位 |
清单的字段和结构以以下文件为准: theme-manifest.schema.json。 字段新增或含义调整时,以该 Schema 和参考主题的 theme. 为准,不要复制旧示例。
六、静态资源制作
默认主题使用 Tailwind CSS v4、Alpine.js 和内联 SVG 图标,但第三方主题可以选择自己的前端 制作方式。服务器只要求最终产物能从 assets/ 直接提供,不会在安装主题时运行 Node.js 或 联网下载依赖。
使用默认主题工具链时:
cd ujcms-starter/src/main/webapp/themes/1/acme
npm ci
npm run build开发 CSS 时可运行:
npm run watch默认主题的构建过程包括:
- 从
_src/icons.json生成snippets/。icon. html - 将运行期需要的第三方文件复制到
assets/vendor/。 - 将
_src/style.css编译压缩为assets/。css/ style. css
资源制作要求:
- 发布 ZIP 必须包含已经构建完成的 CSS、JS、字体和运行时所需的第三方依赖文件。
- 不要把
node_modules/放进主题包。 - Tailwind 必须扫描
templates/、layout/、snippets/、面板模板和相关 JS。 - 后端动态输出的类名不会被普通源码扫描发现,应像默认主题一样用 safelist 或
@source inline(.保留。..) - 页面资源统一使用
${assets}/...,共享运行脚本按规范使用${ctx}/。static/ ... - 图片写准确的
width、height或宽高比,首屏关键图合理设置加载优先级,其余图片懒加载。 - 不依赖公共 CDN,保证私有部署和离线部署可用。
七、本地开发环境
从仓库根目录启动后端:
./mvnw clean spring-boot:run -Dspring-boot.run.profiles=next确保开发数据库中目标站点选择了正在开发的主题。主题目录直接开发适合快速刷新页面;正式交付前 仍要通过 ZIP 上传安装一次,以覆盖安装校验、清单加载、种子导入和主题切换流程,见主题测试与发布。
控制台相关入口:
- 设计 → 主题:安装、更新、预览、激活、演示数据管理和导出主题。
- 设计 → 模板:在线查看或编辑站点主题文件,并使用文件历史恢复。
- 设计 → 页面/构建器:编辑页面区域、面板和页面设置。
- 设计 → 组件库:查看当前主题声明的组件及其设置结构。
- 设计 → 诊断:查看孤立面板 / 页面并恢复或删除,重扫主题注册表。
八、常见问题
CSS 类在开发时有、生产包里没有
先确认发布前执行了生产构建(见“静态资源制作”一节)。Tailwind 动态类需要 safelist 或 @source inline(.;重点检查 区域行列、面板装饰、运行时拼接类和 JavaScript 中使用的类。