Appearance
动态页面配置与发布
Campus
适用角色
仅限内部 SDUI 页面管理员、应用管理员和具备试点授权的实施人员。SDUI 入口按环境启用,非授权账号进入会被跳转到 403。
功能说明
SDUI(Server-Driven UI)用于集中配置和下发老师端、学生端 App 里的动态页面。一个「Schema」对应一个动态页面,它包含页面编码、使用对象、组件树、数据源、规则和灰度范围,发布后由 App 按编码拉取渲染。
页面走草稿 → 校验 → 预览 → 发布 → 历史/回滚闭环:先在 2.0 组件树或 Schema JSON 里编排页面,再用「运行校验」和「App 真机预览」确认,最后发布覆盖同一编码的旧版本。发布过程会保留完整历史,可以随时回滚。
SDUI 是试点/管理员功能,不下发到客户常规菜单;不同环境是否开启以实际下发的客户环境为准。
操作入口
text
系统管理 > SDUI 页面管理(内部入口,按环境启用,非客户常规菜单)截图待补:方案列表、编辑弹窗(2.0 组件树)、发布前对比、App 真机预览二维码。
一、方案列表与筛选
进入 SDUI 页面管理后,首屏是「Schema 列表」。列表列固定为:编码、使用对象、客户、业务版本、Schema、状态、排序、发布时间、操作。
筛选区支持组合过滤:
- 编码:按 Schema code 关键字过滤,可清空。
- 使用对象:全部 / 老师端 / 学生端(按钮式单选)。
- Schema:按 Schema 版本单选(选项由后端汇总生成,例如 1.0、2.0);未选即为全部。
- 客户:填写客户编码定位该客户专属方案,留空视为默认。
- 状态:全部 / 已发布 / 草稿。
工具栏还有:
- 顶部一排「版本药丸」显示各 Schema 版本的总数 / 已发布 / 草稿 / 编码个数,点击可快速切换筛选,再次点击取消。
- 「新增」:新建 Schema 草稿。
- 「迁移清单」:查看每个编码在 1.x 与 2.0 上的现状与建议。
- 「草稿治理」:清理同编码 + 同使用对象 + 同客户下的重复草稿。
若列表页顶部出现橙色提示条「当前页发现 N 组重复草稿」,说明当前筛选下存在同组冗余草稿,建议进入草稿治理清理。
二、新增或编辑 Schema
点击工具栏「新增」,或行内「编辑」进入配置弹窗。弹窗顶部为基础表单,下方为 Tab 化的编辑区。
1. 基础字段
| 字段 | 必填 | 说明 |
|---|---|---|
| 编码 | 是 | Schema code,如 oa.maintain.form。同一 code + 使用对象 + 客户被视为同组。 |
| 标题 | 是 | 页面显示标题。 |
| 使用对象 | 是 | 老师端 / 学生端(表单不允许选「全部」)。 |
| 状态 | 系统显示 | 编辑已发布记录时显示「已发布」,否则显示「草稿」,不可手动改。 |
| 客户编码 | 否 | 留空表示默认版本;填写后仅对该客户生效。 |
| 业务版本 | 是 | 最小 1,同组内递增,用于版本追溯。 |
| Schema 版本 | 否 | 默认 2.0,配合下方组件树使用。 |
| 最低 App 版本 | 否 | 限制可渲染该页面的 App 最低版本。 |
| 排序 | 否 | 影响同编码多方案的取用顺序。 |
| 灰度% | 否 | 0–100 的整数,表示灰度比例。 |
| 灰度用户 | 否 | 指定灰度用户,多个用户用逗号分隔。 |
| 备注 | 否 | 用于记录本次改动/发布/回退的原因。 |
新增时会自动填入一个 2.0 空 Schema(含空 page、body、dataSources、rules)。
2. 2.0 组件树 Tab
这是默认编辑区。顶部工具栏按钮:
- 组件树:抽屉展开当前页面的节点列表,支持选中、复制、删除、拖拽调整层级。
- 初始化 Schema:把当前 Schema 覆盖为 2.0 默认结构(会提示确认)。
- 页面模板:从下拉里选择内置模板(如列表页、表单页等)整页替换,操作前会弹「应用页面模板」确认。
- 组件文档:抽屉展示可用组件目录、示例、字段说明和主题 Token,支持一键把示例添加到当前树。
- 从 JSON 刷新:用 Schema JSON Tab 里的 JSON 覆盖组件树。
- 同步到 JSON:把组件树当前状态回写到 Schema JSON。
- 运行校验:等同底部「校验」,发起发布前 dry run。
- App 真机预览:见后文「四、预览」。
主体分三栏:
- 左侧「组件库」:按分类展开(基础 / 布局 / 输入 / 数据 / 动作 / 业务),点击组件或区块模板加入组件树。
- 中间「预览面板」:可切换结构预览或 Flutter Web 预览(需配置预览地址);切换设备(手机/平板/Web)与主题(默认/业务/暗色)。
- 右侧「属性面板」:四个页签
- 组件:选中节点后编辑 id、type、Props、Bindings、Style、事件、动作、动作序列、条件、表格列、选择器配置等;修改后需点「应用节点」写回。
- 数据源:维护 dataSources,支持增删、批量粘贴 JSON、同步、格式化。
- 主题:切换默认主题、清空,支持逐字段调整并同步文本。
- 规则:管理 setValue / calculate / calculateRows / validate 四类规则,可追加模板、格式化、上下移动。
拖拽、复制、删除操作均以当前选中节点为对象;删除后可通过「组件树」抽屉还原选择。
3. Schema JSON Tab
以文本编辑器直接维护完整 JSON,支持:
- 格式化:一键美化,格式错误会用红条提示。
- 检查 JSON:仅做语法检查,错误信息包含所在行列或字符偏移。
- 刷新组件树:把 JSON 反向解析到 2.0 组件树。
- 预览:实时结构预览,可切换手机 / 平板 / Web 三种画布尺寸。
编辑内容与最近一次保存不一致时,预览面板顶部会有「未保存」状态提示;发布/预览前需要先保存草稿。
4. Fallback JSON Tab
用来配置离线或异常降级页面,提供「格式化」「检查 JSON」两个按钮。字段可留空,表示不启用降级。
5. 发布前校验 Tab
点击「运行校验」执行 dry run,页面会显示:
- 顶部「校验通过 / 不通过」提示条。
- 摘要:页面类型、页面标题、组件数、数据源数。
- 错误(红色)、警告(黄色)明细,逐条列出。
工具栏和底部的「校验」按钮效果一致,校验完会自动切到本 Tab。
6. 弹窗底部操作
固定五个按钮,从左到右:
- 取消:关闭弹窗,未保存内容会丢弃。
- 校验:执行 dry run。
- 发布前对比(编辑现有 Schema 时启用):弹「发布前差异」窗口,和同组最近一份已发布版本做行级 diff。
- 保存草稿:通过表单校验后写入。若正在编辑一份已发布记录,系统会自动另存为新草稿,提示「已另存为草稿 #ID,请使用该草稿预览/发布」。
- 发布:仅在存在编辑对象且当前状态不是「已发布」时启用。
三、保存与发布
保存草稿
点击「保存草稿」触发:
- 校验编码、标题、使用对象、业务版本、Schema JSON 是否填写。
- 若当前在 2.0 组件树 Tab,系统会尝试把工作区同步回 JSON,同步失败(如 JSON 非法)会中止保存。
- 提交后按情况提示:
- 新建:
已保存草稿。 - 编辑草稿:
已保存草稿。 - 编辑已发布记录:如果服务端返回新的草稿 ID,提示
已另存为草稿 #ID,请使用该草稿预览/发布;否则提示已保存为草稿版本。
- 新建:
保存后弹窗关闭并刷新列表。
发布
在列表行「更多 → 发布」或弹窗底部「发布」都可以触发。发布链路:
- 系统会先弹出「发布前差异」窗口,展示「已发布 ID/v 号 → 待发布 ID/v 号」的 JSON 行级对比;首次发布则标注「首次发布」。窗口顶部会统计
删除 / 新增 / 相同行数,并提供「显示相同行」勾选。 - 关闭差异窗口后弹出二次确认:
发布 <code> v<versionNo>?发布前会自动校验,并停用同组其他版本。需要点「确定」才会真正发布。 - 发布成功提示
已发布并刷新列表。
若在编辑弹窗内发布,系统会用当前草稿作为对比右侧;如果组件树未通过本地校验或 JSON 非法,会提前中止并提示原因。
发布前对比(不发布)
- 弹窗底部「发布前对比」或行内「更多 → 发布前对比」:只弹差异窗,不发起发布,方便审阅。
- 编辑弹窗内点该按钮前需先保存草稿,否则提示
请先保存草稿后再对比。
四、预览
App 真机预览
在编辑弹窗工具栏或列表行「更多 → App 预览」触发。前提是已保存过一次草稿。触发后会:
- 校验当前编辑内容与最近一次保存是否一致,若不一致提示
当前编辑内容尚未保存,请先保存草稿后再预览。 - 弹出「App 真机预览」窗口,展示二维码与 App 内路由(形如
/sdui/preview/<id>)。窗口标注:请用 App 首页扫码打开草稿预览。这是 App 内部路由,不是后台 Web 页面,直接粘到浏览器地址栏会 404。- 「复制 App 内路由」「复制扫码链接」两个按钮。
用测试机的 App 首页扫码即可打开该草稿页,便于真机验证。
内嵌 Flutter Web 预览
组件树右侧预览面板支持切换到 Flutter 模式:
- 首次使用需要在输入框填写「Flutter Web 预览地址」并保存,系统会记住到浏览器本地(不同浏览器/账号独立)。
- 内置两个预设:同源(当前后台地址下的
/sdui-preview/路径)、本地(http://localhost:8088/)。 - 预览地址未在同源部署时可能因浏览器策略无法加载;渲染报错会在面板顶部显示错误摘要,并在属性面板高亮相关字段。
预览地址与预览服务由实施人员配置,若窗口一直「iframe 尚未加载」,先联系实施确认预览服务是否可访问。
五、历史版本与回滚
在列表行「更多 → 历史版本」打开历史窗口,列出该编码下的所有版本(ID、业务版本、Schema、状态、标题、备注、发布时间、更新时间)。每行操作:
- 对比:与当前编辑内容或该编码当前版本做行级 JSON diff。
- 回滚:仅草稿行可点(已发布行的回滚按钮为禁用)。点击后弹二次确认
确认回滚到 ID <id> / v<versionNo>?,确认后回滚,提示已回滚并刷新列表与历史。
回滚会以选中的历史版本作为新的当前版本,原始记录仍保留在历史中,可以再次回退。
六、复制草稿治理
「草稿治理」用于清理同一编码 + 使用对象 + 客户下的多份草稿:
- 点击工具栏或提示条上的「草稿治理」打开对话框。
- 系统默认按当前列表筛选扫描最多 500 条草稿状态记录,按分组展示。若真实数量超过扫描上限,顶部会提示
当前仅扫描前 N 条草稿,筛选下共有 M 条;请缩小筛选条件后再治理。 - 每个分组默认「保留」更新时间最新的一份(打「保留」标签);同组其他行可逐条「删除草稿」,或整组点「保留最新并删除旧草稿」批量删除。批量删除前有确认弹窗。
- 操作完成后系统会自动重扫。
已发布的记录不会进入草稿治理范围。
七、迁移清单(1.x → 2.0)
「迁移清单」用于跟进 1.x 页面向 2.0 迁移的进度。窗口按编码 + 使用对象 + 客户分组,列出每组在 1.x 与 2.0 上的状态。
- 顶部单选按钮切换筛选:未完成 / 全部 / 待迁移 / 待发布2.0 / 待切换确认 / 待清理1.x / 已完成,数字为对应条数。
- 支持编码 / 标题 / 客户关键字搜索。
- 每行显示 1.x、2.0 各自最新记录的 ID、业务版本、草稿数,可点「打开」直接跳到编辑弹窗。
- 处理列可点「同组 / 1.x / 2.0」跳回列表并按对应筛选定位。
「已完成」表示 2.0 已发布且 1.x 已清理,可作为迁移验收依据。
关键规则与注意事项
- SDUI 是试点入口,非授权账号访问会被跳转到 403;上线到某个客户前需实施人员评估是否启用。
- 表单校验最少要求:编码、标题、使用对象、业务版本、Schema JSON 都必须填写。
- 编辑「已发布」记录并保存时,系统会自动另存为新草稿,原发布版本不会被就地覆盖。
- 发布前会强制走「发布前对比 → 二次确认」,并在服务端停用同组其他版本;发布前应先确认差异范围与影响客户。
- 预览与发布都要求先保存草稿;有未保存改动时会阻止预览/发布/对比,避免线上和界面不一致。
- 灰度%、灰度用户、最低 App 版本只对本 Schema 生效,不影响同组其他版本。
- Fallback JSON 只是降级使用,不要把主功能写在 Fallback 里。
- 数据源、动作、事件里不要写入密码、密钥、个人隐私或不受控的外部数据。
- Flutter Web 预览地址存在浏览器本地,只影响自己;不同浏览器 / 不同电脑需要各自配置一次。
常见问题
保存时提示表单校验失败
先检查表单顶部的必填项(编码、标题、使用对象、业务版本);再确认 Schema JSON 不为空且格式合法。若在 2.0 组件树 Tab,保存前会尝试把工作区同步到 JSON,组件树里存在无法解析的字段(如 Props/Bindings 文本不是合法 JSON)也会阻止保存,可以先在属性面板的「高级 JSON」里定位错误行列。
发布按钮灰着点不了
发布按钮仅在「已选中记录 + 当前不是已发布」时可用。若正在编辑一份已发布记录,先点「保存草稿」另存为新的草稿版本,再对该草稿发布。
预览提示「请先保存草稿后再预览」或「当前编辑内容尚未保存」
预览走的是服务端已经落库的草稿。请先执行「保存草稿」,保存成功后再点「App 真机预览」。若刚改了组件树,记得先「同步到 JSON」再保存。
App 扫码后打不开或路由 404
App 真机预览是 App 内部路由,不能在普通浏览器打开。请:
- 用测试机安装的 App 首页扫码,而不是微信/系统浏览器扫。
- 确认测试账号已登录并对该使用对象(老师端/学生端)有访问权限。
- 若仍打不开,联系实施人员核对当前环境是否启用了 SDUS 预览与该 grant code 的应用外链。
Flutter Web 预览 iframe 一直未加载
预览需要一个可访问的 Flutter Web 预览地址,一般由实施人员部署。请:
- 先用「同源」或「本地」预设试一次;如果同源部署了预览页,选同源最稳定。
- 若填写自定义地址,注意跨域策略,浏览器可能拦截 iframe。
- 页面顶部若出现红色错误摘要,依据错误信息或高亮字段修正 Schema。
发布后 App 未看到更新
- 确认发布的 Schema 编码、使用对象、客户与 App 请求的一致。
- 让 App 重新进入该页面或退出重登,少数场景需要执行行内「清缓存」清一次服务端缓存。
- 仍异常时对照「历史版本」核对是否发布到了预期的记录 ID,或用「发布前对比」复核 diff。
想撤销一次发布
打开该记录的「历史版本」,选择上一份稳定的草稿点「回滚」;已发布行不能直接回滚,需要先回滚到某个草稿,再重新发布。
同一编码出现好几份草稿
进入「草稿治理」按分组清理,系统会自动保留同组最新的一份。若清理后仍多,检查是不是使用对象或客户编码不同——这属于不同分组,不算重复。
版本记录
| 版本 | 日期 | 修改说明 |
|---|---|---|
| v1.0 | 2026-07-27 | 首次建立 |
| v1.1 | 2026-07-27 | 依据前端源码完善内容 |