GameUI 文档导航

按要实现的界面查文档，不需要按固定课程顺序读完整套手册。

从页面开始

任务	入口
在编辑器中创建页面、选择和修改控件	UI 编辑器基本操作
用代码创建页面、布局和子控件	流式布局指南
选择字号、处理文字溢出、适配屏幕尺寸	UI 字号与可读性、UI 尺寸与适配
响应窗口、横竖屏和安全区变化	ScreenViewport 分辨率变化
初始化没执行、控件不显示或布局错位	常见开发陷阱

流式扩展和对象初始化器都可以创建 GameUI 控件，按项目写法和布局需求选择。链式调用是 API 形式，流式排列是布局行为；两者不等同。

按功能查找

功能	文档
大列表、模板和控件复用	虚拟化列表
UI 属性与绑定	UI 属性系统
拖拽、指针捕获	指针捕获指南、系统说明
长按与触摸反馈	TouchBehavior
Canvas 绘制	Canvas 绘图、Canvas 游戏指南
字体、富文本与链接	自定义字体、Label 富文本
图片、图集与资源路径	自定义 UI 图集、项目资源路径
游戏加载页与进度	Loading 页面
移动摇杆	GameSystemUI 移动控件
背包与快捷栏	GameSystemUI 背包控件
对话与单位气泡	GameSystemUI 对话控件
手牌与卡槽拖拽	GameSystemUI 卡牌控件
命令失败提示	GameSystemUI 命令结果面板

找到可运行的例子

从编辑器的 code_sample 模板创建项目，或查看游戏项目 docs/examples-index.md 指向的模板源码。UI 相关示例包括：

示例目录	关注点
UIFrameworkTest/、ModernUITest/	布局、控件与响应式界面
TouchBehaviorTest/	长按与触摸反馈
VirtualizingPanelTest/	大列表、条目模板与复用
GameUITest/	官方 UI 组件

运行方式和完整索引见官方示例画廊。这些是编辑器游戏项目中的示例，不要求作者构建框架内部测试工程。

虚拟化列表易错点

• ItemTemplate 是 IGameLink<GameDataControl>，不能把创建控件的函数直接赋给它。
• 条目在复用时需要更新显示数据，查看 OnVirtualizationPhase 的模板回调；数据配置中的公式要求见公式赋值位置。
• 核对 ItemSize 与实际条目尺寸；尺寸不符会影响排列和滚动。

验证界面

在目标项目运行，检查最小目标窗口、长文本、目标移动设备、重复打开与关闭。Runtime MCP 可结合 UI 树和截图定位实际矩形、文字和输入；使用方法见 Runtime MCP 调试。

关闭后不再复用的控件调用 Destroy()；RemoveFromParent() 和 ClearChildren() 只摘除关系。手动订阅的全局输入或渲染事件需要在业务结束时取消。完整规则见生命周期陷阱。