Files
UnityAI/modules/frameworks/UI窗口系统/界面拼接.md
2026-10-21 16:38:30 +08:00

247 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# UI 界面拼接
本文是根据示意图制作 UI 窗口的完整规则来源。生命周期和列表 API 见 [UI 开发指南](开发指南.md),通用执行与授权流程见 [工作流清单](../../../rules/40-工作流清单.md)。其他入口只引用本文,不重复维护整套规则。
## 一、输入与目标
开始拼接前,先向开发者确认目标分辨率、横竖屏、SafeArea 与屏幕适配要求,以及窗口是全屏、弹窗还是局部面板。开发者已经明确提供的信息不重复询问;项目现有 CanvasScaler 等配置只能作为参考,不能代替需求确认,也不得直接套用某个项目的分辨率。未确认时可继续检查结构与资源,不先定稿依赖分辨率的切图尺寸和布局。
完整阅读策划正文、备注、状态说明和版本变更,不只查看内嵌效果图。以开发者最新明确要求确定范围;策划文字、旧示意图和现有实现存在冲突时指出差异,不凭旧图恢复已取消的按钮或功能。文档中的建议方案不自动视为已确认需求。
同时检查:
- 设计原图、标注图或 PSD 中的尺寸、间距和层级。
- 项目现有 Sprite、SpriteAtlas、字体、材质和可复用 Prefab。
- 目标窗口名、Prefab 路径、Canvas 层级和脚本绑定方式。
- 示意图对应的状态、滚动区域和本次需要实现的交互范围。
- 区分屏幕 UI、角色头顶 HUD 与关卡场景内容。角色模型、平台、场景背景和世界特效不默认拆成 UI 图片;叠加在关卡上的窗口按需求保持透明。
- 明确不制作的模块是否仍需预留位置,以及可选模块有、无两种状态下的布局;不能把“本次不制作”直接理解为取消布局空间。
先理解当前项目的窗口基类、Item 基类、SFUI/UIMono、资源加载、节点绑定与事件规范,优先复用相似窗口。给出简短的节点、切图、复用和验证方案;已明确授权的方案直接实施。不为拼界面另建框架或修改无关业务、第三方库。
优先复用语义和视觉均匹配的现有资源,或从提供的分层源文件提取。只有示意图时,可以在任务授权范围内拆图、抠图和处理透明边缘;不能只凭截图选择近似资源。缺失或无法准确提取的部分按下述规则明确暴露。
- 新增切图前先检查其他窗口的同类资源,例如头像、头像框、道具和通用按钮。匹配时直接共享引用,不复制成当前窗口的另一套资源;核对加载与打包依赖,不因复用而未经授权改变共享资源的导入设置或其他窗口的显示。
- “全界面精修”应逐项检查实际使用的图片;合格的共享资源可以直接复用,不要求为每张图片重新生成。普通精修保持原有造型、比例、配色和视觉身份,不擅自增加描边、高光或装饰。
### 参考稿、示意图与正式实现
- 已授权按图制作时,默认还原参考稿的轮廓、比例、间距、字体、配色和装饰,不自行重新设计。指定现有资源作为风格基准时,核对实际资源的造型和文字效果,不仅套用相近颜色;只同步到开发者指定的窗口。
- 开发者要求“先给示意图”时,先交付设计预览,确认前不修改对应正式资源和 Prefab。局部示意保留修改区域之外的内容;继续修改时沿用已经确认的设计,明确哪一版、哪部分是本次实施依据。
- 示意图确认后,将效果落实为独立切图、组件和实际布局,不停留在合成图片。设计示意与 Unity 实际渲染截图分别标明;生成或编辑出的示意图不能作为 Prefab 已实现、运行正常的验收证据。
### 缺失与质量问题必须可见
- 始终保证开发者能够明确看到哪儿有问题、哪儿缺东西。记录具体窗口、节点或画面区域,以及缺少的资源、质量问题、影响和需要提供的素材。
- 被遮挡、源图低清、元素不完整或无法干净分离时,报出问题。被其他元素遮挡不等于图标本身存在缺口,不能把遮挡轮廓当成最终图标轮廓,也不用其他图片、假数据或隐藏节点掩盖问题。
- 仅授权抠图时,裁剪、透明边缘处理和尺寸调整只处理已有可见内容,不默认补画、重绘、生成式填补或猜测还原。开发者已明确要求补齐被遮挡轮廓、修复缺失区域或重绘时,按其授权范围实施,无需重复确认;说明哪些部分经过修复,不能将修复结果称为原始切图的准确恢复。
- 对照预览中,在问题位置使用明确的诊断文字或标注框,例如“缺少关闭按钮素材”“图标无法完整提取”;标注是给开发者定位问题的诊断信息,不是替代美术资源,也不能混入正式运行资源。不能仅依赖容易被忽略的空白或控制台日志。
- 暂时无法渲染时,先提供具体节点路径、资源路径或示意图区域说明,并按 [工作流清单](../../../rules/40-工作流清单.md) 修复验证环境;恢复后补充可视化标注。问题可以保留为待解决项,但不能宣称对应资源或视觉效果已验收完成。
## 二、推荐层级
```text
WindowName
├── ImgBg
├── HeaderArea
├── ContentArea
│ ├── StaticContent
│ └── ListView
│ └── viewport
│ └── content
│ └── ItemTemplate (inactive)
├── FooterArea
└── PopupOrEffectArea
```
- 按视觉和功能边界组织节点,不为每个图片增加无意义容器。
- 节点命名应能对应脚本字段和功能,例如 `Btn_Close`、`Txt_Title`、`Img_Icon`。
- 复用 Item 或子面板时保持独立根节点,便于 UIMono 绑定和对象复用。
- 全屏背景使用稳定锚点;局部模块使用明确尺寸,避免依赖编辑器当前分辨率。
- 背景主要承载底板和固定装饰;关闭按钮、页签、操作按钮及其状态独立实现,不烘焙在背景中。
- 动态名称、进度、数量和提示使用文字组件;固定装饰性标题可以使用图片,但不能妨碍交互、适配及明确要求的本地化。
- 道具图标、数量底图和数量文字独立组织。深浅底色、轮廓或状态不同时使用对应资源,不用道具卡底板替代数量底图,也不把示例数字烘焙进底图。
- 不用整张效果图替代可交互窗口;按示意图核对整体轮廓、比例、间距、层级和遮挡关系。
## 三、画布与图片尺寸
- 以开发者确认的分辨率建立基准画布,按适配要求统一 CanvasScaler、Sprite PPU 与项目约定。
- RectTransform 缩放默认保持 `1`,主要通过尺寸、锚点和布局控制显示,不靠缩小 Transform 匹配超大源图。
- **普通、不可拉伸的图片,执行 `SetNativeSize()` 后应达到目标画布中的预期尺寸。** 检查导入后的 Sprite 尺寸及 PPU 与 Canvas 的关系,不能只检查源 PNG。
- 三宫格、九宫格图片使用紧凑源图,通过 RectTransform 设置最终显示尺寸。
## 四、切图与资源效率
- 每个独立 UI 元素默认使用单张图片,**Sprite Mode 默认 Single**。开发者有单独要求时,允许 Multiple 或其他组织方式,不作绝对禁止。
- Sprite Mode 与图集打包分别处理;Single 图片仍可按项目规范进入 SpriteAtlas。名称应表达用途和状态。
- **普通图片在保证 `SetNativeSize()` 尺寸正确、最终显示不模糊的前提下,以尽量少占内存、尽量快加载为原则。** 避免超过实际需求的像素尺寸,不用过度降采样或压缩牺牲清晰度。
- 去除无用透明留白,保留标准图标画布要求的留白,以及必要的阴影、描边、柔边和装饰;裁剪后同步调整定位,保持视觉位置一致。
- 清除毛刺、杂点、残留底色、白边和黑边,在浅色、深色及透明棋盘背景下检查完整轮廓。区分图形内部的有效高光与图外的残留描边,不能通过新增白边掩盖抠图问题。缩小到实际显示尺寸后重新检查,不能只验收原始大图。
- 按目标平台、透明通道和图片内容选择纹理格式与压缩;Mipmap、Read/Write、过滤和图集设置按用途配置,不盲目沿用默认值。
- 不单凭磁盘文件大小判断运行时内存与加载效率;需要比较方案时,以导入信息及目标平台测量为依据。
- 缩放、压缩或打图集后检查最终导入和渲染结果。
### 图集归类与标准图标
沿用项目既有命名与加载方式,优先按以下职责归类,避免每个窗口复制一套共享素材:
| 类别 | 收录范围 |
|---|---|
| 道具图集 `ItemIcon` | 道具表图标字段对应、符合项目统一画布尺寸的标准图标 |
| 头像图集 | 跨窗口复用的标准头像;头像框按项目既有约定归属 |
| 通用 UI 图集 | 跨功能通用的按钮、面板底板、提示框等资源及其状态 |
| 功能图集 | 其余仅供对应功能使用的图标、装饰和展示插画 |
| 大幅场景背景 | 按项目资源加载方式单独管理,避免混入小图标与通用控件图集 |
- `ItemIcon` 的标准尺寸从项目现有规范和实际资源核实,不把某个项目的像素值作为通用标准。核对道具表实际图标字段;空值和占位值不自动生成图片,也不为迁就目录分类修改配表。
- 礼物表等其他业务表的图标不因尺寸一致就归入 `ItemIcon`。战斗大图、奖励插画和皮肤卡等非标准展示素材放入所属功能图集,不能用它们覆盖道具表的标准图标。
- 标准图标保持统一画布和一致的视觉占比,按原比例缩放并补必要透明留白,不能直接拉伸成正方形。确有标准图标和功能大图两种用途时,分别保留合适版本。
- 品质框、品质底图等配套资源按复用范围与共同加载关系归类。项目明确约定跟随标准 ItemIcon 使用的通用品质背景可随 ItemIcon 管理;商城等功能专用版本保留在对应功能图集,不因同为品质资源就强行合并。
- 分类优先表达用途;是否进一步拆分图集,应依据共同加载、释放时机及目标平台的实际打包结果,不只按文件夹名称或图片数量判断。
### 相同与相似资源复用
- 批量整理前核对用途、视觉样式、状态、画布、PPU、清晰度与全部使用尺寸。同名、同含义或外观相近不等于可以直接替换;完全重复的资源也需核对引用后再合并。
- 能共用底板时,文字、数量底图、数量文字及固定图标分别组织;不把带示例文字或图标的整张合成图直接当作可拉伸底板。已有复合图无法安全拆分时保持比例,不为减少图片数量强行合并。
- 底色与边框始终同步变化、采用相同拉伸方式时可以合成一张;品质、选中、试穿或已穿戴等独立变化的视觉层分别处理。状态之间是否共用表现由当前界面的确认稿决定,不默认把品质色当成选中色。
- 旋转或镜像后仍符合视觉与方向含义的提示图标可以共用同一张 Sprite。先核对箭头流向、尖端位置和光照阴影,不因左右对称就默认镜像,也不为可安全复用的方向额外生成重复图片。
- 合并和迁移时同时核对 Prefab/场景引用、运行时代码中的图集与 Sprite 名称、配置表和生成工具;动态名称加载不能只靠 GUID 引用搜索验证。删除旧资源前完成替代路径验证。
- 源图像素减少不等于图集页数或运行时显存减少;报告收益时区分源图变化、实际图集打包尺寸和目标平台测量结果。
## 五、三宫格与九宫格
- 仅纵向伸缩的图片优先纵向三宫格,仅横向伸缩的图片优先横向三宫格。
- 同时改变宽高的规则面板、卡片和按钮优先九宫格。
- Border 必须保护圆角、描边、阴影和固定装饰;拉伸区域选择适合伸展的纯色、渐变或规则区域。
- 修改共用图片的切片方式前核对所有引用尺寸,包括默认隐藏的弹窗、空列表面板和提示框;兼有横向与纵向拉伸用途时,不能降为单轴三宫格。
- 切片比例需与各控件的实际显示尺寸匹配,必要时按节点调整 `Image.pixelsPerUnitMultiplier`;检查固定边缘的显示厚度和装饰比例,不用整体拉伸图标或文字补偿底板尺寸。
- 可以缩减源图中可拉伸区域的像素尺寸,保留固定边缘;检查最终尺寸下的接缝、渐变和装饰是否自然。
- Border 不得越过固定图标、文字或装饰;左右边界之和、上下边界之和不能超过 Sprite 尺寸,并保留有效的中心拉伸区域。不能仅因中心颜色相近就认定它适合拉伸。
- 复杂插画、不规则图标或无法合理分离拉伸区域的图片,不强行切片。
- 修改源图尺寸后重新检查 Border,并配置对应 Image 的切片显示方式,不能只写 Border 而仍按普通图片整体拉伸。
## 六、组件、布局与交互
- 使用项目对应的 SFUI 图片、文字、按钮、Toggle、ScrollRect 等组件,以及既有节点行为和绑定流程。
- 组件接口、序列化与初始化以当前项目源码为准,不凭名称或原生 UGUI 经验推断。
- 按适配要求配置锚点、pivot、布局约束与遮罩;避免布局组件互相冲突或依赖偶然执行顺序。
- 纯装饰图片与文字关闭不必要的射线检测,避免遮挡按钮、页签和滚动操作。
- 角色 RT 的旋转指引若仅作提示,使用不拦截输入的图片,由既有拖动区域接收操作,不擅自改成旋转按钮。指引锚点跟随 RT 或模型展示区域,按确认稿保持位置、间距和方向,避免遮挡角色;不能只在某个屏幕尺寸下用绝对位置凑出效果。
- 点击区域与视觉表达一致,必要时按项目约定扩大;检查长文本、数量位数及动态内容变化。
- 可选模块显隐时同时处理其标题、底板、分隔线和点击区域,并按确认的规则让相邻内容居中或重排;保留占位也是明确的布局选择,不能偶然留下空洞或隐藏热区。
- 为暂不制作的操控模块预留安全区内的锚点和空间,其他内容不得侵入。尺寸按当前需求确定,不将某个项目的像素值写成通用标准;预留节点不渲染、不拦截输入,标记只放在审核预览中。后续补入控件时同步更新预留节点、生成源与验证条件。
## 七、页签与共享内容
- 互斥页签使用 **Toggle + ToggleGroup**;SFUI 项目使用对应的 SFUI Toggle。
- 普通态与选中态由 Toggle 状态驱动;监听变化时仅在选中状态执行切页,正确设置默认选中项并避免初始化重复刷新。
- 除非开发者或项目另有要求,不用普通按钮和独立布尔变量重复实现页签状态。
- 展示结构一致的页签共用一个内容面板、列表和 Item 模板,切页更新数据与必要状态,不复制两套完整界面。
- 文字、图标、奖励或进度不同不是新增模板的理由;只有结构确实不同时才增加模板。
- 明确切页是否回到顶部、同页更新是否保持滚动位置。
## 八、列表选择与复用
- 动态列表优先使用项目的 **SFUI_ScrollRect**。先读取当前实现和使用示例,再选择 `BindEvent` 或项目已接入的 LoopListView2 / LoopGridView 包装,不能混用或因拼 UI 强行迁移。
- 固定容量的头像条等可按项目实现使用静态内容模式;不为少量固定节点额外接入虚拟化或业务数据。以下模板与复用要求按实际选用的列表机制应用。
- 明确滚动内容与固定内容的边界:列表 Item 放入 Content,按设计保持固定的标题、统计等留在滚动内容之外;配置正确的 Viewport、遮罩和拖拽射线入口,不能仅添加 ScrollRect 组件而仍依赖静态排列。
- `BindEvent` 按数据索引动态选择模板;参数职责、刷新入口和其他包装示例统一见 [UI 开发指南](开发指南.md)。
- 使用列表已有的创建与复用机制,不额外手动批量生成节点。
- Item 每次刷新完整更新文字、图标、进度、按钮状态、可选节点与高度,避免旧状态残留及回调持有过期数据。
- 模板保持禁用,尺寸、pivot 和滚动方向匹配;组件遵循当前框架要求,不重复序列化由列表运行时添加的组件。
- LayoutGroup/ContentSizeFitter 是否保留或关闭取决于当前列表实现;不要混用不同包装的布局机制。
## 九、数据与生命周期边界
- 仅拼 UI 时,不擅自扩展协议、数据模型和业务逻辑。
- 接入业务时由管理器持有和更新业务数据,通过项目事件机制通知界面;采用 CTC 的项目使用 CTC 刷新。
- 界面负责展示与转交操作,不自行维护另一份权威业务状态。
- 订阅和解除成对,重复开关、启用窗口及 Item 复用不能叠加监听;生命周期具体约定见 [UI 开发指南](开发指南.md)。
- 预览数据与正式运行数据分离,不能覆盖服务器状态。
- 参考图中的商品、装扮、价格和数量不自动成为正式配表或库存;缺少业务接入时明确显示待接入状态,不在界面中伪造购买、穿戴或保存成功。
## 十、拼接流程
1. 按 [AI 接入入口](../../../ai/AI接入入口.md) 读取规则和 UI 指南,完成本文的需求确认。
2. 检查目标 Prefab 是否已存在,导出或读取当前层级,避免覆盖有效结构。
3. 枚举目标资源目录和图集,建立设计元素到实际资源的对应关系。
4. 确定窗口根尺寸、锚点、主要功能区和列表类型。
5. 使用 Unity Editor 手工拼接,或通过 MCP 的 JSON 生成工具创建基础结构。
6. 绑定 SFUI/UIMono 组件与脚本,按已授权范围补齐交互、列表和数据。
7. 刷新资源并检查 Console、Prefab 序列化结构和运行时显示。
8. 按本文验收清单对照原图检查实际画面和交互。
JSON 生成适合批量创建稳定层级和组件,不代替视觉校对、业务绑定和运行时验证。
## 十一、修改已有 Prefab 与资源维护
- 先读取现有 Prefab 和脚本引用,再调整层级或组件。
- 移动、重命名节点前搜索 `FindUICtrlByName`、序列化字段和生成绑定代码。
- 移动或重命名资源优先使用 Unity 的资源管理接口,例如 `AssetDatabase.MoveAsset`,保留 `.meta` 和 GUID。先确认相关 Prefab 编辑状态及自动保存,防止旧路径被重新创建;完成后核对类名、文件名、窗口资源 attribute、AssetBundle 路径、生成源及旧引用。
- 只修改目标节点,避免让 Unity 重序列化无关 Prefab。
- 组件勾选状态属于 Prefab 行为的一部分;修复显示问题时同时检查 `enabled` 与 GameObject active。
- 若已授权迁移到会关闭旧布局的列表包装,可保留旧组件序列化参数作为参考,运行时由新包装管理布局;不将该行为套用到所有列表实现。
- 原始示意图、源图和中间素材保存在约定的美术或策划归档目录,运行时目录只保留实际需要的资源。
- 删除资源前检查 Prefab、场景、代码、配置、图集和生成工具引用,并遵守开发者授权范围。
- 有生成工具时同步修改生成源,避免重新生成旧布局或无用资源;不能只手工修补生成结果。
- 替换已有资源时尽量保留 GUID,避免引用断裂;保留用户已有的无关修改。
- 修改 Sprite Mode 或源图尺寸后检查是否残留过期的切片记录;通过 Unity 的 Sprite 导入接口清理,并验证引用的 Sprite 对象及本地 fileID。保留 GUID 不代表原有子 Sprite 引用仍然有效。
- 任务临时辅助文件的保留与清理统一遵循 [工作流清单](../../../rules/40-工作流清单.md#9-临时辅助文件与收尾)。审核画面等明确交付物与临时诊断材料分开管理。
## 十二、验收与交付
在开发者确认的目标分辨率及必要的适配尺寸下实际渲染,保存可复核的对照画面并检查:
- Prefab 路径和窗口 attribute 一致。
- Sprite、字体、材质和图集引用有效。
- 锚点、pivot、sizeDelta 和层级与设计目标一致。
- 按钮、文本、列表、进度和弹窗交互正确。
- 背景、装饰、整体比例、间距、颜色和字体符合示意图,普通图片 SetNativeSize 尺寸正确且清晰。
- 逐项检查当前窗口实际引用的图片,包含正常态、禁用态与可选节点;共享资源引用正确,数量底图与文字独立,被遮挡轮廓的处理符合授权,精修前后有可复核的对照。
- 三宫格、九宫格在全部受影响的实际宽高下,边角、接缝、渐变和拉伸效果自然;主动展开隐藏弹窗与相关状态,不能只验收默认界面或独立切片示例。压缩、打图集后的透明边缘和清晰度符合要求。
- 图集成员归属、实际打包后的 Sprite 和运行时名称加载正确;合并后没有遗漏配置引用、重复归属或失效 Sprite 引用。
- 页签普通态、选中态、内容切换正确,同结构页签共享列表和模板。
- 空列表、短列表、长列表、首尾可达、内容尺寸变化及 Item 复用正常;实际拖拽方向正确,视口边缘裁剪正常,固定元素不随 Content 移动。
- 可选模块有、无两种状态均验证,显隐后的间距、居中或重排符合需求;预留区在目标分辨率和安全区下不被其他内容侵入。
- 极长文本、不同分辨率和重复打开不破版,业务涉及的未完成、可操作、已完成、禁用等状态正确。
- 重复切页、开关及启用窗口无重复回调、状态残留或缺失引用。
- Unity Console 无本次新增 Error,运行时实际显示通过确认。
编译通过、Prefab 保存成功或 JSON 生成成功不能代替视觉和交互验收。资源缺失与质量问题必须按本文在预览和交付中明确标出;验证环境不可用时,按 [工作流清单](../../../rules/40-工作流清单.md) 先修复再验证。无法自行解除的阻塞明确说明,保持相关检查未完成,不能仅报告“未验证”便宣称任务完成。
发现变形时,对照原始素材、修改前布局及当前实际画面定位原因,区分素材原有比例和本次引入的问题。空白画面、占位图或缩得无法判断细节的预览不算视觉验证通过;先修复预览条件,再按实际显示尺寸检查。
Prefab 编辑视图与运行时显示不一致时,检查 CanvasScaler、SafeArea、父级锚点和缩放、LayoutGroup/ContentSizeFitter/AspectRatioFitter 等布局驱动,以及窗口初始化、数据刷新和动画对属性的覆盖。确定实际控制布局的来源后修改,避免仅调整编辑器画面,或新增另一套相互覆盖的运行时布局常量。
交付时说明修改的窗口、脚本和资源,确认的基准分辨率与适配方式,共享资源与修复素材的范围,主要图片尺寸及三宫格/九宫格设置,已完成的编译、视觉和交互验证,以及未验证内容、已知限制和必要后续操作。明确区分 Editor 离屏预览、Play Mode 运行和目标设备验证,不能将叠加场景的审核预览表述为真实对局已接入或真机已验收。
## 十三、可复用任务指令
以下模板只填写本次任务的输入与授权边界,具体制作、验证和收尾要求引用本文,不在其他入口复制整套规则。
```text
请先按 UnityAI 的 ai/AI接入入口.md 读取规则,再按“UI 界面拼接”执行本次任务。
策划案:<路径与版本>
布局参考图:<路径与版本>
风格基准及需保留的内容:<指定资源或已确认稿>
目标窗口与修改范围:<窗口名、仅哪些界面或区域>
画布与适配:<分辨率、横竖屏、全屏/弹窗、SafeArea>
功能范围:<仅拼 UI / 接入哪些交互与业务;哪些区域需要预留>
素材处理授权:<仅提取已有内容 / 允许修复、补画或重绘的具体范围>
当前阶段:<先出示意图 / 按已确认稿正式实施>
先检查完整策划、现有 Prefab、共享资源及图集,简述布局、复用、切图与验证方案后推进。
已确认的信息不重复询问;缺少必须由开发者决定的条件时先确认,继续不依赖该条件的工作。
完成后提供实际界面截图、修改文件、资源缺口与验证边界,并按工作流清理临时辅助文件。
```
## 文档关联
| 文档 | 关联原因 |
|---|---|
| [UI 窗口系统](README.md) | 窗口框架和资源路径 |
| [UI 开发指南](开发指南.md) | 生命周期和虚拟列表接口 |
| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | MCP JSON/Prefab 工具 |
| [MCP 使用规则](../编辑器工具/MCP工具/Codex_Unity_MCP使用规则.md) | Codex 与 Unity 的调用规则 |