技能介绍

为什么我们需要这份指南

在 Cocos Creator 3.8.x 中写 UI 时，动态排版往往是 bug 的重灾区。特别是在处理不定长文本时，如果你还在用 NONE 模式预估高度，或者在代码中盲目用 new Node() 拼凑界面，很容易遇到文字溢出边界、多行文本堆叠成一团、或者修改了 .ts 代码但运行结果纹丝不动的诡异现象。本技能针对这些高频坑位整理了直接可用的规则与排查链路。

核心能力与工作流

1. 基于 `RESIZE_HEIGHT` 的排版规范

对于长度不定的多行文本，本技能遵循官方推荐，强制使用 RESIZE_HEIGHT 模式。这意味着你必须显式设置 lineHeight（且数值 >= fontSize），并利用锚点贴边定位。技术原理在于：该模式下引擎会自动计算高度，手动估算或手动设高在引擎层面是无效的，只能通过显式的 lineHeight 来约束文字块。

2. 编辑器预览与增量编译机制

当我们在代码中修改 UI 逻辑时，只要编辑器未最小化且预览运行中，Cocos 会自动增量编译并刷新浏览器。但请注意：窗口最小化会导致 watch 停止。
遇到代码不生效时，请遵循以下排查链路：

首先检查 chunks/ 目录下的文件 mtime 是否更新；
保持编辑器在前台，等待几秒看是否自动编译；
只有在确认未开启预览或 mtime 长时间未更新时，才强制退出编辑器全量重开。

3. 常见 Bug 速查与自检

针对文字溢出边框或元素被画布裁掉的问题，技能内置了速查表。例如，当面板边框被裁时，往往是本地坐标算错导致世界坐标越界，此时建议使用 getWorldPosition 复核边界。

适用边界与注意事项

职责划分：本技能专注于开发阶段的 UI 编写与 bug 修复。项目脚手架搭建、纯逻辑解耦以及场景 JSON 序列化请交由 cocos-project-scaffold 处理。
自动化测试：本技能不内置浏览器驱动。对于 UI 走查，请使用专用的 cocos-preview-bsk-test 技能。
渲染验证原理：在自动化测试中，由于 WebGL canvas 在 preserveDrawingBuffer=false 时无法读取像素，验证渲染必须依赖浏览器 compositor 抓图，而不能使用 drawImage 读取 canvas 内容。