原生 NGUI 界面规范

本页适用于选择 Studio 内原生 NGUI 的 Mod 窗口。Framework 同时支持 WebView2 窗口，选型和共同要求见 Mod 窗口开发规范。

NGUI 方案要求

NGUI 窗口的窗口壳、输入设置、结果面板与播放控制使用 Studio 原生 NGUI 体系。

不得使用 OnGUI、GUI.Window、GUILayout，也不得另建 UGUI Canvas 作为正式交互界面。原生菜单入口不等于窗口已经原生化——窗口里的控件同样要遵守本规范。

挂载方式

Studio UI 就绪后，从 Unity 主线程调用 StudioAPI.CreateWindow(gameObject, title, width, height)。返回的 NativeModWindow 提供 Content、AddLabel、AddButton、Show、Hide 和 Dispose。

var window = StudioAPI.CreateWindow(gameObject, "Mod 设置", 480, 300);
window.AddLabel("准备就绪", new Rect(0, 0, 440, 28));
window.AddButton("执行", new Rect(0, 40, 120, 32), delegate {
    // Unity 主线程上的业务逻辑。
});
window.Show();

关闭按钮默认调用 Hide()，再次打开可调用 Show()；Dispose 后需要重建。owner GameObject 销毁后底层窗口会清理，Mod 卸载时也应主动 Dispose。

• 窗口挂到 Studio 现有的 UI 层级，使用现有 UIRoot、UICamera 和 UIPanel。
• 不得创建第二套事件相机，不得修改共享 UI 的缩放、深度和图集。
• 优先使用适用的原生窗口预制体/工厂——框架已提供 StudioAPI.CreateWindow()（返回挂到现有 UIRoot 下的 NativeModWindow）和 StudioAPI.ImportWindowLayout()（从 JSON 布局导入），见 StudioAPI 门面。确需创建控件时，使用 UILabel、UISprite、UIButton、UIInput、UIToggle、UISlider、UIScrollView 等原生 NGUI 类型，沿用 Studio 的图集、字体、背景、按钮状态和间距。

克隆原生控件的注意事项

克隆原生控件前检查其业务脚本和事件绑定：

• 解除与原功能的绑定，只保留所需的显示和控件组件。
• 不得复制原窗口的保存、删除或其他业务回调。
• 复用颜色和字体时不得改写共享资源。

布局导入

布局导入属于 NGUI 规范。使用 StudioAPI.ImportWindowLayout(gameObject, absolutePath) 或 ImportWindowLayoutJson(gameObject, json) 读取 .layout.json，返回 ImportedModWindow。通过 Get<T>(id) 查找控件、BindClick(id, callback) 绑定按钮、Window.Show() 显示窗口；事件通常只在首次导入时绑定。关闭后可复用，卸载时 Dispose。

Unity 导出工具位于 Framework 的 tools/unity-layout/，格式与完整使用说明位于 Framework/docs/layout-import.md。当前接口读取布局数据，不直接加载 .prefab 或 AssetBundle。

事件与生命周期

• 事件通过对应 NGUI 控件的原生回调绑定（按钮 onClick、输入框 onSubmit、选择/滑块 onChange）。
• 窗口关闭或插件卸载时解绑回调，并销毁插件自己的节点。
• 重复打开不得重复订阅或残留遮罩。

焦点与输入

• 模态窗口必须接入 Studio 的焦点与输入阻挡机制；编辑输入框时不得同时触发模型快捷键。
• 非模态播放面板应允许操作视图。
• 按 Esc、关闭按钮、切换模型和插件卸载时的行为必须明确。

适配与可访问性

• 窗口需适应 UI 缩放和分辨率；长列表用 NGUI 滚动视图，长诊断允许换行或滚动。
• 错误和欠约束状态同时给出文字，不能只用颜色表达。
• 输入错误保留用户已填数据。

线程

UI 创建、更新与销毁都在 Unity 主线程执行。耗时计算与文件读写不得放在 NGUI 的逐帧布局/刷新回调里。

交付检查清单

• [ ] 正式窗口中不存在 IMGUI / 独立 Canvas
• [ ] 点击、输入焦点、Tab / Esc 行为正常
• [ ] 滚动、分辨率与 UI 缩放适配正常
• [ ] 反复开关不残留节点与订阅
• [ ] 模型切换、插件卸载时正确清理
• [ ] 用 Studio 实际程序集编译，并在 Studio 内实际显示验收

静态检查不能代替实际验收

本规范适用于新增正式 GUI 和后续 GUI 改造。F10 调试覆盖层仍是 IMGUI 实现，不应作为新插件 GUI 的范例。网页报告属于独立导出文件，不属于 Studio 内 GUI。