离线调试：用设计器预览你的 UI

以往的mcbe前端开发只有真正注入到游戏后才可见，布局跑偏、JS 报错在游戏里都不直观，耗时耗力。好消息是，项目自带的 App 设计器（Tauri + Vite 桌面应用）提供离线预览。现在你不用进游戏，就能直接在画布上渲染你声明的模组 UI，并把页面脚本的 console / 错误接到界面上，帮你把”改一下 → 进游戏看”的循环缩短成”改一下 → 画布即时刷新”。

离线预览帮你省一次进游戏，但真机仍须回验。 设计器用近似引擎渲染，图标、贴图等资源是近似还原；真正上线前请回到游戏里过一遍。

本页以 dearoreui-ExampleMod（课程 04 完整日历）为例，讲清整条离线调试路径。

获取App 

前置：设计器做了什么

设计器的核心是 模组 UI 自动识别（源码扫描） ——它静态扫描你选择的模组源码目录里的 registerComponent 注册，自动识别其中的 UI 页面， 你的模组无需专门适配 。

• 双加载模型：既支持独立模组入口预览，也支持「原版屏幕 + 模组覆盖层」组合预览。
• 近似引擎：复用核心层布局脚本，以接近真机的 HtmlSanitizer / 布局规则渲染。
• 侧边标签页：只展示模组识别出的页面，未改动页面不显示。

第一步：打开模组目录

启动 App 设计器后，从顶部菜单选择：

项目 → 打开模组目录

在弹出的目录选择框里点选你要预览的模组源码目录。目录会显示在左侧资源面板顶部，确认无误后继续。

扫描是静态分析，只读，不会修改你的模组或触发构建。选错目录也不会破坏任何东西，重新「打开模组目录」即可。

第二步：自动识别 + 选中页面

扫描完成后，左侧标签页会列出自动识别出的 UI 页面。点击任意一项即可在右侧画布看到实时预览：

打开的是示例模组的完整日历（课程 04）：全屏半透明 backdrop、居中卡片、月历网格与日期点选都应在此画布上先出现。如果某项识别不出，日志区会给出原因，而不是只留一个空白标签。

进阶用法

改分辨率调试

画布窗口拖拽改变尺寸后，预览脚本会监听 window.resize，按新视口重跑布局并重渲染——用来验证「任何分辨率下都居中、可读」。

示例日历为此用了显式像素几何（position:absolute + 具体 left/top/width/height），而不是 flex-grow 撑满。这是这个客户端的布局限制，离线画布同样遵守，方便你在预览阶段就暴露这类问题。

查看页面日志 / console

页面脚本的 console、报错与警告会被桥接到设计器的日志面板，分类着色展示：

• 顶部菜单 帮助 → 页面日志 打开日志面板；
• 事件与页面调试试错，都能在这里先看到，不必进游戏翻客户端日志。

文件改动自动刷新

设计器内置目录监听。你改动的课程源文件（如 scripts/ex04_calendar.js 的 .css 逻辑）保存后，画布会自动重载预览。

导入原版资源（贴近真机）

想要更接近真机显示，可从菜单：

项目 → 导入原版资源

选择游戏目录 <game>/data/gui/dist/hbui，导入原版主题 CSS、字体、图集与 DOM，用于本地贴图预览。该菜单当前仍为占位/计划中能力，本文档不把它当作已交付事实来描述；未导入时，图标、贴图等资源以纯 CSS 近似渲染。

关键约束：预览 ≠ 真机

离线画布帮你解决”布局和 JS 能不能跑通”的问题，但它是近似引擎，记住这些边界：

离线预览的价值在于：在你按下进游戏按钮之前，先把布局跑偏、脚本报错、位置错位这类高频问题清掉。 图标细节、贴图还原、真实性能这些画布看不出来，最后一定要回游戏按 environment 页的清单复验。

验证和排查

• 没有任何标签页：检查「打开模组目录」是否指向了源码目录，且目录里确实有 registerComponent 调用。
• 某页面预览空白：看日志面板是否报了 HtmlSanitizer 拒绝或布局解析失败；security 相关错误往往意味着 htmlBody 里混入了不安全的 <script> 外链或事件属性。
• 画布和真机不一致：先对照上表确认是否属于「近似渲染」范畴；若布局层级对不上，优先检查是否用了文档禁止的 100vw/100vh、拖拽重建网格子树、或动画动了 top/left/width/height。

继续阅读

• 在你的模组中使用 DearOreUI
• 快速入门
• 工具链
• 设计资源