5.8 KiB
角色属性头像选择设计
背景
Client/Assets/Script/xmain/Module/Player 下已有角色资料数据、资料存储和 HUD/详情面板。PlayerProfileData 已包含 AvatarId，但现有界面只显示固定的占位头像，用户无法选择头像。
当前工作区已有 54 张头像资源：
Client/Assets/Game/Art/UI/Texture/Icon/GamerPic/GamerPic_01.png ～ GamerPic_54.png
本功能在现有角色资料系统上增加头像选择能力，并提供独立的选择界面。
目标
- 在角色资料详情中提供“更换头像”入口。
- 展示 54 张可选头像。
- 支持点击头像后即时预览，但只有点击“确认”才保存。
- 确认后同步刷新资料详情、HUD 和其他依赖玩家资料的头像展示。
- 保持已有
AvatarId = 0的旧数据兼容。 - 使用项目现有的异步资源加载、JSON UI 描述和 Prefab 生成规范。
非目标
- 不新增头像解锁、付费、分类或搜索功能。
- 不修改角色战斗属性、职业或等级系统。
- 不实现服务端头像保存协议；本次只更新现有客户端
PlayerProfileStore数据。 - 不重构现有 UI 资源目录或处理与本需求无关的工作区资源变更。
方案
采用固定 JSON/Prefab 槽位方案，而不是运行时创建网格。
新增 UI_PlayerAvatarPicker Dialog 预制体，固定包含 54 个头像槽位。每个槽位直接引用一个 GamerPic_XX Sprite，运行时代码只处理选择、高亮、预览和确认。这样布局可在 Unity 编辑器中检查，资源引用稳定，也符合项目 UI 持久化规范。
数据与资源
AvatarId 规则
0：兼容旧存档，显示GamerPic_01。1～54：对应同编号的GamerPic_XX。- 负数或大于 54：显示默认头像，不阻塞界面。
- 用户点击确认后保存
1～54。
资源目录
- 头像：
Client/Assets/Game/Art/UI/Texture/Icon/GamerPic/ - 通用 UI 资源：使用当前工作区中已有的
Client/Assets/Game/Art/UI/Texture/UI/Common/资源。 - 头像选择预制体：
Client/Assets/Game/Art/UI/Prefab/UI_PlayerAvatarPicker.prefab - 头像选择 JSON：
Doc/UIPrefabCreater/UI_PlayerAvatarPicker.json
组件边界
PlayerAvatarCatalog
新增头像目录类，负责：
- 暴露头像数量和默认头像 ID。
- 将头像 ID 转换为
GamerPic_XX资源路径。 - 将旧 ID、负数和超范围 ID 归一化为可显示的默认头像。
目录类不保存玩家状态，也不处理 UI。
PlayerProfileModule
扩展现有角色资料模块，负责：
- 异步加载并刷新 HUD、详情面板中的头像。
- 绑定详情面板的头像入口。
- 异步打开和关闭头像选择弹窗。
- 持有临时
pendingAvatarId，隔离预览状态与已保存资料。 - 更新选择槽位高亮和预览头像。
- 点击确认时更新
PlayerProfileStore。
异步回调必须校验当前视图仍存在，且回调对应的头像 ID 仍是当前请求，避免关闭界面或快速切换时旧回调覆盖新状态。
PlayerProfileStore
继续作为玩家资料的唯一状态源。确认头像时通过已有 Update 接口修改 AvatarId，由 Changed 事件驱动所有资料视图刷新。
界面设计
资料详情面板
- 保留现有昵称、UID、职业、货币和战斗属性布局。
- 头像区域增加可点击的“更换头像”入口。
- 当前头像继续使用头像框包裹，并替换内部固定占位图。
头像选择弹窗
挂载到 UILayer.Dialog，包含：
- 遮罩层：点击后取消选择。
- 弹窗标题：
选择头像。 - 当前头像预览区：头像框、预览头像和选择提示。
- 可滚动头像列表：6 列 × 9 行，共 54 个头像槽位。
- 每个头像槽位：头像 Image、选中高亮 Image、点击 Button。
- 底部按钮：
取消、确认。 - 右上角关闭按钮：等同取消。
界面使用现有蓝绿描边弹窗、深色文字、TextMeshProUGUI 和通用按钮/列表资源。头像 Image 保持等比显示。
交互流程
- 用户打开角色资料详情。
- 用户点击头像区域或更换入口。
- 模块异步加载并实例化头像选择弹窗。
- 弹窗以当前资料头像初始化
pendingAvatarId和选中态。 - 用户点击任意头像时，只更新预览和选中高亮。
- 点击取消、关闭或遮罩时销毁弹窗，不调用
PlayerProfileStore.Update。 - 点击确认时调用
PlayerProfileStore.Update保存头像 ID，然后关闭选择弹窗。 PlayerProfileStore.Changed触发 HUD、详情面板和头像展示刷新。
异常处理
- 头像资源加载失败：保留
ico_user占位头像并记录一次错误日志。 - 头像 ID 非法：按默认头像显示，不抛出 UI 阻塞异常。
- 重复点击打开：只允许一个选择弹窗实例。
- 关闭弹窗后仍返回的异步加载：丢弃回调结果。
测试与验收
EditMode 测试
- 验证头像 ID 到
GamerPic_XX路径的映射。 - 验证 0、负数和超范围 ID 都回退默认头像。
- 验证取消不会触发资料变更事件。
- 验证确认只修改
AvatarId，不改变其他资料字段。 - 验证头像变更后资料模块刷新 HUD 与详情视图。
- 验证
UI_PlayerAvatarPicker.json通过 JSON Prefab Builder 校验。
Unity 编辑器验证
- 头像选择预制体可正常加载。
- 54 个头像槽位排列为 6 列 × 9 行并可滚动。
- 当前头像有选中高亮。
- 点击头像会更新预览但不会提前保存。
- 确认、取消、关闭和遮罩点击行为符合交互流程。
- 确认后的头像同时出现在资料详情和 HUD。
验收标准
用户进入角色属性详情后，点击头像可以打开选择界面；选择任意头像可以即时预览但在确认前不保存；点击确认后头像 ID 保存并同步更新详情页和 HUD；取消选择后原头像保持不变。