补充图片素材选择器设计文档

新增 UI 编辑器图片素材选择器的状态、交互与验收合同。
2026-09-03 13:45:27 +08:00
parent 8ed0626627
commit df8b22f71f
1 changed files with 41 additions and 0 deletions
@@ -0,0 +1,41 @@
+# UI 编辑器图片素材选择器
+
+> 更新时间：`2026-09-03`
+
+## 目标
+
+在 UI 编辑器 Inspector 的图片组件中，用独立 modal 图片选择器替换原生素材下拉框，使用户绑定素材时可以看到现有预览图或缩略图。
+
+## 数据来源与边界
+
+- 素材列表继续使用 Inspector 当前的 `sprites`，顺序沿用 `Object.entries(sprites)`。
+- `SpriteAsset` 不新增缩略图字段。预览继续消费 UI 编辑会话已有的 `previewUrls: Record<string, string>`；预览缺失不影响素材绑定。
+- `previewUrls` 由 Inspector projection 沿 `NodeInspector → ComponentPanel → ImagePanel` 传入选择器。
+- 本次不新增后端接口、持久化字段、搜索筛选或二级大图预览。
+
+## 交互合同
+
+### Inspector 触发区域
+
+- 正常绑定显示素材名称。
+- 空值显示 `未绑定`。
+- 引用不存在的素材显示 `素材不存在（<ID>）`，保留原 ID，不在打开面板时自动清除。
+- 未绑定时按钮文案为 `选择素材`；已有绑定或失效引用时为 `更换素材`。
+- `readOnly` 时按钮禁用，不能打开选择器。
+
+### 素材选择 modal
+
+- 使用现有 `ThemedModal`，带遮罩、关闭按钮、Esc 关闭和点击遮罩关闭。
+- modal 内容使用纵向 flex；素材区域占据剩余空间并内部滚动，modal 设置最大高度。
+- 素材以弹性网格展示，卡片包含预览图和素材名称，图片使用 `object-contain`。
+- 有预览时显示 `previewUrls[id]`；无预览或加载失败时显示棋盘格背景与 `ImageIcon` 占位，素材仍可选。
+- 当前绑定项显示选中边框或标记。
+- 第一项为明确的“清除选择”，点击立即写入 `null` 并关闭。
+- 点击任意正常素材立即写入其 ID 并关闭；重复点击当前素材也按相同流程处理。
+- 当前失效引用保留为禁用信息卡，显示 ID；用户仍可使用“清除选择”。
+- 素材为空时显示 `暂无可用素材`，保留关闭操作。
+- 卡片支持 Tab 聚焦以及 Enter/Space 选择；关闭后焦点返回触发按钮。
+
+## 验收
+
+自动化测试覆盖：打开/关闭、按钮和名称状态、当前项高亮、选择 ID、清除 `null`、缺预览占位、失效引用、空列表、`readOnly` 禁止打开、键盘选择和遮罩关闭。实现后运行定向测试、前端类型检查、编码检查及 `git diff --check`。