组件、区域与演示数据
校对日期:2026-11-16。适用于社区版及全部商业版(在可视化构建器中编排区域需高级版)。
本文面向主题开发者,说明怎样为可视化构建器提供组件(Shape)和可编排的区域,以及怎样随主题提供演示数据(种子数据)。 管理员在构建器中的操作见页面组件与内容编排;主题的组成和目录结构见主题开发。
一、可视化组件与区域
1.1 Shape 定义
区域中的一个面板对应一个 Shape 实例。一个纯设置组件的最小定义如下:
shapes/:
{
"$schema": "https://www.ujcms.com/schema/composition/shape.schema.json",
"name": "Notice",
"version": "1.0.0",
"label": { "zh-CN": "公告", "en": "Notice" },
"description": "显示一段页面级公告。",
"tags": ["content"],
"presentation": {
"icon": "text",
"group": { "zh-CN": "内容组件", "en": "Content" },
"order": 10
},
"settings": {
"title": {
"type": "text",
"required": true,
"default": "公告",
"label": { "zh-CN": "标题", "en": "Title" }
},
"body": {
"type": "text",
"default": "",
"label": { "zh-CN": "正文", "en": "Body" }
}
}
}name 必须采用 PascalCase(各单词首字母大写)命名,version 必须是语义化版本。
settings 中每个字段的定义可包含 type(必填)、required、label、description、help、group、default、 deprecated、visibleWhen、of、fields:
- 字段类型:
text、longText、html、number、boolean、date、datetime、enum、media、link、badge、themeColor、freeColor,引用类型articleRef、channelRef、blockRef、voteRef,以及list、object。 - 条件显示:
visibleWhen写成{ "字段名": 值或值数组 },仅当所列字段取指定值时才显示本字段。 - 引用字段:管理员在构建器中选择文章、栏目、区块或投票,模板拿到的是展开后的摘要对象(标题、地址、图片等), 失效的引用会在保存“更新未修改项”时被修复。
- 列表与对象:
list用of声明元素定义,object用fields声明子字段;list元素为object时即页面本地 编排的条目列表。 - 数据查询:可选的
data块声明条目来源。from走服务端查询,items引用一个list设置作为手工条目;两者 兼有时用mode引用一个enum设置切换,取值manual时跳过查询。查询参数中可用$settings.*与$ctx.*占位。 - 版本升级:只新增可选字段、放宽约束或补默认值属兼容改动,静默生效;字段改名须在
migrations中用rename声明;新增必填字段或收紧约束可加载,但受影响的面板会在“健康”中提示;删除字段、改变类型或未声明的改名会被拒绝 重新加载,旧定义继续生效。migrations按from版本范围(1.x、1.2.x或精确版本)声明rename、default、remove、transform(copy、const、remove三种操作)。
完整示例见参考主题 shapes/*.json;Schema 可由 GET / 取得。
1.2 面板模板
Shape Notice 对应 snippets/,文件名大小写必须与 Shape.name 一致:
[#escape x as (x)!?html]
<section class="rounded border p-4">
<h2>${settings.title}</h2>
[#if settings.body?has_content]
<p>${settings.body}</p>
[/#if]
</section>
[/#escape]面板模板可使用:
settings:解析后的组件设置。items:Shapedata查询或手工列表产生的条目。panel:当前面板元信息。
需要文章、栏目或区块数据的组件可声明 Shape data 查询(见“Shape 定义”一节的“数据查询”), 写法以 GET / 返回的 Schema 和参考主题 shapes/*.json 为准,不要在模板里拼接不受控查询字段。
1.3 在页面渲染区域
在页面清单中声明区域并允许 Notice 后,在对应模板位置加入:
[@region name='main'/]区域结构由“区域 → 行 → 列 → 面板”组成。系统预置了八种行布局:full、halves、 thirds、quarters、twoThirdsLeft、twoThirdsRight、sidebarLeft、sidebarRight。主题负责确保后端区域指令可能输出的 响应式栅格类被 CSS 构建工具收录;默认主题通过 Tailwind @source inline(. 显式保留这些类。
如果多个页面共享同一个区域,可在一个页面清单中完整声明区域,其他页面用:
{
"kind": "region",
"shared": "site"
}共享区域的规则:
- 被引用的页面必须属于同一主题,且对同名区域做了完整声明;引用方只能写
kind与shared两项。不能连续引用其他 共享引用,也不能引用自身;引用不存在的页面会导致主题加载失败。 - 渲染时,引用页面没有自己的行就回退到宿主页面的默认行。管理员可在构建器中用“仅此页面定制”把该页面分叉,再用 “恢复为全站共享”还原。
- 种子只写在宿主页面上(如
seed/中regions/ site. regions. json "page": "site"),写在引用页面上的区域种子会被跳过并在 导入摘要中提示。 - 页面清单中没有声明的区域,其种子会被跳过并给出警告;补上声明后重新激活主题即可导入。
1.4 区域脚本刷新
可视化构建器可能只替换某个区域的 HTML,不重新执行被替换内容中的 <script>。如果面板需要 JavaScript 初始化,应让主题公共脚本监听:
document.addEventListener('ujcms:region-refreshed', (event) => {
initThemeWidgets(event.target);
});初始化函数应可重复调用,并限制在 event.target 区域内,避免重复绑定全页事件。
二、制作演示数据
演示数据是可选能力。若主题必须依赖特定栏目、区块或首页面板才能呈现设计效果,建议随包提供 不会覆盖用户已有修改的种子数据。
2.1 区域种子
seed/:
{
"$schema": "https://www.ujcms.com/schema/composition/seed-regions.schema.json",
"page": "home",
"regions": {
"main": {
"rows": [
{
"id": "seed-home-notice",
"layout": "full",
"columns": [
{
"panels": [
{
"component": "Notice",
"settings": {
"title": "欢迎使用 Acme 主题",
"body": "可在设计器中修改或删除本公告。"
}
}
]
}
]
}
]
}
}
}page 和区域名必须分别匹配页面清单的 name 与 slots。行 id 应稳定;每行列数必须与 layout 对应,面板组件必须在区域 allowedShapes 中。
2.2 内容种子
内容种子可包含:
- 字典和内容模型。
- 栏目、文章和专题。
- 区块、投票、问卷、表单类型和链接组。
seed/下的图片、视频和附件。content/ assets/
导入按依赖顺序执行,先字典和模型,再导入内容,最后导入区域。常用可移植引用包括:
| Token | 用途 |
|---|---|
{{asset: | 把演示媒体复制到上传存储并替换为公开 URL |
{{channel: | 引用站点栏目 |
{{article: | 引用主题来源文章 |
{{block: | 面板设置中引用区块 |
{{vote: | 面板设置中引用投票 |
{{theme}} | 引用主题自身的展示资源前缀 |
文件按类型放在 seed/content/ 下:channels.(栏目:originId 必填且在主题内唯一,alias 默认取 originId,parent 为父栏目的 originId,channelModel / articleModel 为模型名称)、articles/ (originId,channel 为栏目别名或 originId)、topics/、blocks/、votes/、 surveys/、forms/、link-groups/、models/、 dicts/。每种文件的完整字段以参考主题 themes/ 中的同名文件为准。 栏目、专题种子中的 alias 键就是后台的「别名」(URL 中使用的 slug,见模板编写的“固定链接与别名”一节),种子文法不随字段改名而变化。
种子应满足以下原则:
- 使用稳定的
originId和别名,主题升级时不要随意改名。 - 不携带用户提交、计数、审核流程状态或生产敏感数据。
- 允许导入多次,且不覆盖管理员已经修改的内容。
- 主题在选择“不导入演示数据”时仍能正常渲染空状态。
- 在低版本或低商业级别缺少某项功能时,应跳过不支持的功能并给出说明,避免整个主题安装失败。
安装主题时,种子范围有三种:none、composition、all。控制台默认可只导入页面布局; 需要完整演示站时,由管理员选择 all。
三、常见问题
组件在构建器中不可选
依次检查:
shapes/*.json是否通过 Schema。- Shape
name是否为 PascalCase。 - 页面清单的
allowedShapes是否包含该名称。 snippets/是否存在且大小写一致。panels/ <Shape. name>. html - 主题注册表是否已在安装、更新或本地文件变更后重新加载。
区域种子没有导入
确认安装时种子范围不是 none;种子 page、区域名必须已在安装主题自己的页面清单中声明。 共享区域的种子数据只能定义在声明该区域的页面中。默认执行“导入演示数据”时,会跳过已存在的区域; 如需重建,请在“演示数据管理”中点击“还原演示数据”(见主题测试与发布的“更新主题”一节)。