# 示例(六)动画、拆分与注册 前面五步已经把网格、详情、滚动与交互拼起来了。最后一步补三件事:让选中态与提示动起来、把代码落回五个文件、把面板注册成 `GameUI` 并从打开处接入。 ## 前置知识 阅读本篇前,建议先读完: - [示例(五)交互与状态](./inventory-example-5-state.md) - [自定义组件](./custom-components.md) - [UI 系统](./ui-system.md) ## 最后一步要收什么 收尾不是「再加一个功能」,而是把前面五步已经写下的东西固定下来: ```text src/client/ui/ ├─ inventory/ │ ├─ inventory-panel.tsx InventoryPanel:根容器、标题、关闭、共享状态 │ ├─ item-grid.tsx ItemGrid:行容器数组、行列计算、选中/装备比较 │ ├─ item-cell.tsx ItemCell:单个格子的背景、名称、数量与描边 │ ├─ item-detail.tsx ItemDetail:详情、描述与未选中提示 │ └─ action-bar.tsx ActionBar:装备 / 使用 / 关闭按钮 └─ index.ts 导出 InventoryUI,供打开处引用 ``` 每个文件的职责在示例(一)就定好了,这里只是把它们落到真实路径。下面依次说明动画挂在哪、最终组装怎么核对、注册与打开怎么写、以及一份可以逐项验证的清单。 ## 动画作用在树的哪一层 动画只驱动响应式值,不重建组件。本篇只做两处: - **面板呼吸描边**:面板主体之后加一个同样大小的描边矩形,只改它的 `alpha`。 - **提示淡出**:底部提示文字只改 `alpha`,文字内容仍由 `hint` 决定。 ```tsx import { onMounted, onUnmounted, ref, watch } from 'vue'; const pulse = ref(0.4); const hintAlpha = ref(1); // 上一次提示变化的时间,用来算淡出进度 let lastHintAt = 0; let raf = 0; const tick = (now: number) => { // 0~1 之间来回变化,只驱动描边的 alpha const phase = (now % 1600) / 1600; pulse.value = 0.35 + Math.sin(phase * Math.PI * 2) * 0.3; // 提示变化后 1.2 秒内淡到 0.4,之后保持 const since = now - lastHintAt; hintAlpha.value = since < 1200 ? 1 - (since / 1200) * 0.6 : 0.4; raf = requestAnimationFrame(tick); }; // 提示一变就重新计时,动画不参与提示内容的计算 watch(hint, () => { lastHintAt = performance.now(); hintAlpha.value = 1; }); onMounted(() => { raf = requestAnimationFrame(tick); }); onUnmounted(() => { // 组件卸载后必须停掉,否则回调会继续访问已销毁的组件 cancelAnimationFrame(raf); }); ``` 两个动画节点都挂在面板根容器下: ```tsx { /* 呼吸描边:只改 alpha,不重建组件;noevent 不拦截点击 */ } ; { /* 提示:内容来自 hint,只有透明度在动 */ } ; ``` 描边与提示都是面板的兄弟节点,不进入 `ItemGrid` 或 `ItemDetail` 的 props 链,所以动画不会改变数据流:`items` 仍由面板持有,`selectedId` 仍由点击驱动,格子的描边仍由 `selected` / `equipped` 决定。`noevent` 让描边只负责好看,不参与命中;不加它,整块面板的点击都会被这层描边接走。 `pulse` 每帧只写一个数字,元素属性跟着变;组件本身不会重新创建。停止动画放在 `onUnmounted`,否则页面切走后回调仍在跑。仓库里另有 `transitioned` / `transitionedColor` 渐变工具,返回值是 `ITransitionedController<...> | null`,使用前必须判空;本篇不依赖它,避免把可空值带进每一帧。 ## 最终组装与契约核对 六篇共用的系列契约逐条对照最终代码: | 契约 | 内容 | 最终写法 | | ---- | ------------------- | ----------------------------------------------------------------------------------------------- | | 1 | `items` 的形态 | `InventoryPanel` 里 `const items = ref(...)`;子组件收 `items.value`,派生用 `computed` | | 2 | `Item` 来源 | 只在示例(二)定义一次,后续文件 `import` 同一份类型 | | 3 | `selectedId` 空值 | `ref(null)`;未选中显示「请选择道具」;「取消选择」写回 `null` | | 4 | 关闭归属 | 面板调用 `props.controller.close(props.instance)`;子组件只 `emit('close')` | | 5 | 左侧最终方案 | `Scroll`;示例(二)的普通网格是阶段性实现,示例(四)已替换 | | 6 | 布局坐标(layout) | 左侧 `[54, 100, 400, 280]`、右侧 `[470, 100, 196, 280]`、操作条 `[54, 392, 304, 32]` | | 7 | 组件拆分与 props 链 | `InventoryPanel → ItemGrid → ItemCell`;`ItemDetail` 与 `ActionBar` 平级接收结果 | | 8 | key | 格子 `key={item.id}`;行容器 `key={row}`,因为行只表示位置 | | 9 | 事件流 | `ItemCell → ItemGrid → InventoryPanel`;操作条 `emit` 后由面板决定动作 | 最终组装的骨架(省略内部细节): ```tsx … (selectedId.value = id)} /> (selectedId.value = null)} /> ``` 如果前面某一页的写法与本表冲突,以本表为准:左侧只有 `Scroll` 一个方案,`selectedId` 只有 `null` 一种空值,关闭只有面板一个入口。前面页面已经写过的坐标若与这里不同,按这里替换;本篇不再给第二个方案。 本表与最终骨架里的坐标都相对 720×480 根容器:面板主体矩形自己画在 `[30, 30, 660, 420]`,标题 `[54, 52]` 直接相对根容器,不要再套一层 `[30, 30]` 的容器;否则标题会被再加一次偏移。 最终骨架里那层同尺寸的 `container [0, 0, 720, 480]` 是面板根:外层是画布根,里层是面板根(实际代码用 `hidden` 控制开合)。新内容加到面板根这一层,不要加到画布根上;两层的 `loc` 相同,所以坐标写法不变,但层级职责分开。 ## 注册与打开 `InventoryPanel` 与 `GameUI` 在同一个文件里导出: ```tsx // inventory-panel.tsx:把名字与组件绑成一个对象 import { GameUI } from '@motajs/system'; export const InventoryUI = new GameUI('inventory-panel', InventoryPanel); ``` `src/client/ui/index.ts` 再统一导出,打开处只认这个对象: ```ts // src/client/ui/index.ts export { InventoryUI } from './inventory/inventory-panel'; ``` 打开时把对象交给控制器,返回值就是这次打开的实例: ```tsx // 从主 UI 栈打开 const instance = props.state.mainUIController.open(InventoryUI, {}); // 关闭时把同一个实例交回去(面板内部用 props.instance 拿到它) props.state.mainUIController.close(instance); ``` 打开时传的是 `GameUI` 对象本身,名字不参与查找;构造与命名的规则见[第 1 篇「UI 通用模板」](../basics/ui-template.md#gameui-是一个对象不是名字)。 关闭当前面板、马上打开另一个面板时,用 `props.controller.keep()` 包住切换,用完调用 `safelyUnload()`,避免背景闪一下;用法见[「UI 系统」的「keep」](./ui-system.md#keep)。 ## 最终验证清单 按下面的顺序点一遍,每一项都对应一条事件路径或一处树位置: | 验证项 | 操作 | 预期 | 对应路径 | | -------- | ----------------------- | ---------------------------------------- | ---------------------------------------------- | | 打开 | 从主 UI 栈 `open` | 720×480 面板出现,右侧显示「请选择道具」 | 控制器创建实例 → `props` 注入 → 根容器挂载 | | 选中 | 点一个格子 | 格子高亮,右侧显示名称、数量、描述 | `ItemCell → ItemGrid → InventoryPanel` | | 取消选择 | 点详情底部「取消选择」 | 高亮消失,右侧回到「请选择道具」 | `ItemDetail` 发 `clear` → 面板写 `null` | | 滚动 | 滚轮 / 滚动条 / 按钮 | 行整体上下移动,滚动条位置同步 | `Scroll` 内部处理,格子坐标不变 | | 装备 | 选中后点「装备」 | 按钮变「已装备」,该格子描边变绿 | `ActionBar` 发 `equip` → 面板写 `equippedId` | | 使用 | 点「使用」 | 数量减一,提示刷新,数量为 0 时按钮变淡 | `ActionBar` 发 `use` → 面板改 `items` / `hint` | | 关闭 | 点标题栏关闭 / 底部关闭 | 面板卸载,背景恢复 | 面板 `close()` → `controller.close(instance)` | | 再次打开 | 再 `open` 一次 | 回到初始状态:未选中、滚动在顶部 | 新实例 → 新状态 | 关闭后动画必须停:如果 `cancelAnimationFrame` 漏了,再次打开会看到两个循环同时在改 `pulse`,边框呼吸会变得忽快忽慢。这也是清单里「再次打开」要单独验证的原因。 清单里的「再次打开」按 `close` 写:`close` 会卸载实例,再 `open` 得到新实例,所以未选中、滚动在顶部。如果你改用 `hide` 隐藏面板,实例与滚动位置都会保留,这一行的预期要相应改成「回到隐藏前的位置」;两种语义的区别见[第 7 篇「显示开关」](../basics/layer-transform-performance.md)与[「UI 系统」的「隐藏与显示」](./ui-system.md#隐藏与显示)。 ## 运行效果 下面是完整面板的 live:网格、详情、滚动、装备 / 使用、关闭与动画都在。关闭后可以用「重新打开」按钮回到面板。 ## 边界与注意 - 动画在卸载后必须停。`onUnmounted` 里调用 `cancelAnimationFrame`,不要只停一次。 - 动画节点不要进入子组件的 props 链。只改面板自己节点的 `alpha`,数据流保持单向。 - 拆分后 Props 要逐层传。不要用全局变量绕过父子关系,否则读者无法从文件结构看出数据流。 - 注册只是把名字和组件绑成一个对象,不写入名字查找表。不要按名字取 UI,也不要做全局注册表。 - 最终 live 如果跑不起来,保留代码与说明,不要删内容;先确认真实客户端环境与依赖是否齐全。 - 性能建议先测再改。`hidden`、`Scroll`、`key` 与组件粒度是四条固定口径,不要为了「看起来更快」额外加缓存。