Shiliang/UnityAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

【整合】 框架使用规则

Browse Source
This commit is contained in:
Shiliang
2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
modules/frameworks/UI窗口系统/界面拼接.md
View File

@@ -1,192 +1,80 @@
# UI 界面拼接设计指南
# UI 界面拼接
## 一、界面结构设计原则
## 一、输入与目标
### 1.1 模块化拆分
开始拼接前同时确认：
将界面按功能划分为独立模块：
- 设计原图、标注图或 PSD 中的尺寸、间距和层级。
- 项目现有 Sprite、SpriteAtlas、字体、材质和可复用 Prefab。
- 目标窗口名、Prefab 路径、Canvas 层级和脚本绑定方式。
- 目标分辨率、SafeArea、横竖屏和滚动区域。
| 模块类型 | 功能定位 | 示例 |
|---------|---------|------|
| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 |
| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 |
| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 |
| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 |
不能只凭截图选择近似资源。设计图中的可检查对象必须使用语义正确的现有资源；缺失资源应明确记录，不能用无关图片顶替。
### 1.2 经典布局模式
## 二、推荐层级
```
┌─────────────────────────────────────────────────────┐
│ TopArea (信息展示 + 可收起功能按钮) │
├──────────┬───────────────────────┬──────────────────┤
│ Left │ │ Right │
│ Area │ CenterArea │ Area │
│ (状态) │ (核心功能入口) │ (功能面板) │
│ │ │ │
├──────────┴───────────────────────┴──────────────────┤
│ BottomArea (快捷功能 + 状态信息 + 输入) │
└─────────────────────────────────────────────────────┘
```text
WindowName
├── ImgBg
├── HeaderArea
├── ContentArea
│ ├── StaticContent
│ └── ListView
│ └── viewport
│ └── content
│ └── ItemTemplate (inactive)
├── FooterArea
└── PopupOrEffectArea
```
---
- 按视觉和功能边界组织节点，不为每个图片增加无意义容器。
- 节点命名应能对应脚本字段和功能，例如 `Btn_Close`、`Txt_Title`、`Img_Icon`。
- 复用 Item 或子面板时保持独立根节点，便于 UIMono 绑定和对象复用。
- 全屏背景使用稳定锚点；局部模块使用明确尺寸，避免依赖编辑器当前分辨率。
## 二、组件拆分方法
## 三、列表选择
### 2.1 基础组件识别
- 单列或单行滚动：LoopListView2。
- 固定多列或网格：LoopGridView。
- 模板节点保持禁用，尺寸、pivot 和滚动方向必须匹配。
- 虚拟列表不依赖旧 LayoutGroup/ContentSizeFitter 运行时排版。
- 具体初始化接口见 [UI 开发指南](开发指南.md)。
| 组件类型 | 识别特征 | 处理方式 |
|---------|---------|---------|
| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` |
| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` |
| **图片** | 图标、背景图 | 使用 `SFUI_Image` |
| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` |
| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` |
## 四、拼接流程
### 2.2 复合组件封装
1. 读取 [UnityAI README](../../../README.md) 中的 UI 入口和相关指南。
2. 检查目标 Prefab 是否已存在，导出或读取当前层级，避免覆盖有效结构。
3. 枚举目标资源目录和图集，建立设计元素到实际资源的对应关系。
4. 确定窗口根尺寸、锚点、主要功能区和列表类型。
5. 使用 Unity Editor 手工拼接，或通过 MCP 的 JSON 生成工具创建基础结构。
6. 绑定 SFUI/UIMono 组件与业务脚本，补齐交互、列表和动态数据。
7. 刷新资源并检查 Console、Prefab 序列化结构和运行时显示。
8. 对照原图检查尺寸、层级、颜色、字体、九宫格和点击区域。
将功能相关的基础组件组合为复合组件，便于复用和维护：
JSON 生成适合批量创建稳定层级和组件，不代替视觉校对、业务绑定和运行时验证。
**设计原则**：
- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条）
- 提供统一的数据设置接口
- 保持组件之间的逻辑独立性
## 五、修改已有 Prefab
---
- 先读取现有 Prefab 和脚本引用，再调整层级或组件。
- 移动、重命名节点前搜索 `FindUICtrlByName`、序列化字段和生成绑定代码。
- 只修改目标节点，避免让 Unity 重序列化无关 Prefab。
- 组件勾选状态属于 Prefab 行为的一部分；修复显示问题时同时检查 `enabled` 与 GameObject active。
- 列表迁移后，旧布局组件可保留序列化参数作为参考，但运行时由新列表包装关闭。
## 三、预制体层级规范
## 六、验收
### 3.1 标准层级结构
```
WindowName (RectTransform)
├── ModuleName (RectTransform) # 模块容器
│ ├── ComponentName (SFUI_*) # 功能组件
│ ├── SubModule (RectTransform) # 子模块
│ └── CollapsibleArea (RectTransform) # 可收起区域
└── BtnCollapse (SFUI_Button) # 收起控制按钮
```
### 3.2 命名规范
| 类型 | 命名规则 | 示例 |
|-----|---------|------|
| 模块容器 | PascalCase + Area | `TopArea` |
| 功能组件 | PascalCase | `BtnCollapseTop` |
| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` |
| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` |
---
## 四、收起/展开功能设计
### 4.1 功能定义
| 按钮 | 控制区域 | 用途 |
|-----|---------|------|
| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 |
| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 |
### 4.2 设计要点
**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。
**交互逻辑**：
1. 点击收起按钮时，切换对应区域的显示/隐藏状态
2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标）
**布局要求**：
- 收起按钮应放置在对应区域的边缘位置，便于用户找到
- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制
- 收起状态应在窗口生命周期内保持记忆
---
## 五、实际案例：主界面拼接
### 5.1 模块化设计思想
**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。
**模块归类方法**：
1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部）
2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区）
3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群）
**层级关系示例**：
```
Window
├── TopArea (一级：位置)
│ ├── InfoPanel (二级：信息展示)
│ │ └── TxtWelcome (三级：具体组件)
│ └── FuncButtons (二级：功能按钮)
│ └── BtnUpload (三级：具体按钮)
└── LeftArea (一级：位置)
└── PlayerPortrait (二级：复合组件)
├── ImgAvatar (三级：头像)
└── BarHP (三级：血条)
```
**设计要点**：
- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块）
- 独立交互功能作为独立模块（如收起按钮单独作为控制模块）
- 可收起区域作为独立子模块，便于统一控制显示/隐藏
---
## 六、界面拼接流程
### 6.1 设计阶段
1. **需求分析**：明确界面功能和交互需求
2. **模块划分**：将界面拆分为独立功能模块
3. **层级设计**：设计预制体层级结构
### 6.2 开发阶段
1. **组件创建**：创建基础组件和复合组件
2. **预制体搭建**：按层级结构搭建预制体
3. **脚本编写**：实现交互逻辑和收起/展开功能
### 6.3 测试阶段
1. **功能测试**：验证所有按钮和交互功能
2. **收起测试**：测试收起/展开功能正常工作
3. **适配测试**：验证不同分辨率下的显示效果
---
## 七、注意事项
1. **组件复用**：相同功能的组件尽量复用，减少冗余
2. **状态管理**：收起状态需要正确保存和恢复
3. **图标反馈**：收起按钮图标应随状态变化
4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建
5. **命名规范**：统一的命名规则便于维护和查找
---
## 八、JSON 配置驱动的 UI 生成方式
本项目支持通过 JSON 配置快速生成 UI 预制体，详细工具说明、命令格式和部署步骤见 [UI 拼接工具](../编辑器工具/UI拼接工具.md)。
UI 相关人员核心工作流程：读取设计效果图和碎片图片，生成 JSON 配置文件，再通过工具自动生成 Unity 预制体。
---
**版本**: v1.2
**适用**: StrayFog 框架 UI 拼接开发人员
---
- Prefab 路径和窗口 attribute 一致。
- Sprite、字体、材质和图集引用有效。
- 锚点、pivot、sizeDelta 和层级与设计目标一致。
- 按钮、文本、列表、进度和弹窗交互正确。
- 空数据、极长文本、不同分辨率和重复打开不破版。
- Unity Console 无本次新增 Error，运行时实际显示通过确认。
## 文档关联
> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
| 文档 | 关联原因 |
|---|---|
| [UI 窗口系统入口](README.md) | 本文件是 UI 窗口系统模块的子文档 |
| [UI 开发指南](开发指南.md) | 窗口开发与界面拼接互相补充 |
| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | JSON 驱动 UI 生成工具说明 |
| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | UI 命名与资源规则互相引用 |
| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
| [UI 窗口系统](README.md) | 窗口框架和资源路径 |
| [UI 开发指南](开发指南.md) | 生命周期和虚拟列表接口 |
| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | MCP JSON/Prefab 工具 |
| [MCP 使用规则](../编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md) | Codex 与 Unity 的调用规则 |