13 KiB
示例(六)动画、拆分与注册
前面五步已经把网格、详情、滚动与交互拼起来了。最后一步补三件事:让选中态与提示动起来、把代码落回五个文件、把面板注册成 GameUI 并从打开处接入。
前置知识
阅读本篇前,建议先读完:
最后一步要收什么
收尾不是「再加一个功能」,而是把前面五步已经写下的东西固定下来:
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决定。
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);
});
两个动画节点都挂在面板根容器下:
{
/* 呼吸描边:只改 alpha,不重建组件;noevent 不拦截点击 */
}
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
stroke
strokeStyle="#f2b84b"
alpha={pulse.value * 0.6}
noevent
/>;
{
/* 提示:内容来自 hint,只有透明度在动 */
}
<text
loc={[54, 432]}
text={hint.value}
fillStyle="#8fb6ff"
alpha={hintAlpha.value}
/>;
描边与提示都是面板的兄弟节点,不进入 ItemGrid 或 ItemDetail 的 props 链,所以动画不会改变数据流:items 仍由面板持有,selectedId 仍由点击驱动,格子的描边仍由 selected / equipped 决定。noevent 让描边只负责好看,不参与命中;不加它,整块面板的点击都会被这层描边接走。
pulse 每帧只写一个数字,元素属性跟着变;组件本身不会重新创建。停止动画放在 onUnmounted,否则页面切走后回调仍在跑。仓库里另有 transitioned / transitionedColor 渐变工具,返回值是 ITransitionedController<...> | null,使用前必须判空;本篇不依赖它,避免把可空值带进每一帧。
最终组装与契约核对
六篇共用的系列契约逐条对照最终代码:
| 契约 | 内容 | 最终写法 |
|---|---|---|
| 1 | items 的形态 |
InventoryPanel 里 const items = ref<Item[]>(...);子组件收 items.value,派生用 computed |
| 2 | Item 来源 |
只在示例(二)定义一次,后续文件 import 同一份类型 |
| 3 | selectedId 空值 |
ref<string | null>(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 后由面板决定动作 |
最终组装的骨架(省略内部细节):
<container loc={[0, 0, 720, 480]}>
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
<g-rect
loc={[0, 0, 720, 480]}
fill
fillStyle="#000000"
alpha={0.35}
noevent
/>
<container loc={[0, 0, 720, 480]}>
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
/>
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
stroke
strokeStyle="#f2b84b"
alpha={pulse.value * 0.6}
noevent
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
<container loc={[626, 50, 56, 32]} onClick={close}>
…
</container>
<container loc={[54, 100, 400, 280]}>
<Scroll ref={scroll} loc={[0, 0, 372, 244]} padEnd={16}>
<ItemGrid
items={items.value}
selectedId={selectedId.value}
equippedId={equippedId.value}
columns={5}
cellSize={66}
gap={8}
onSelect={id => (selectedId.value = id)}
/>
</Scroll>
</container>
<container loc={[470, 100, 196, 280]}>
<ItemDetail
item={selectedItem.value}
onClear={() => (selectedId.value = null)}
/>
</container>
<container loc={[54, 392, 304, 32]}>
<ActionBar
canEquip={canEquip.value}
canUse={canUse.value}
equipped={isEquipped.value}
onEquip={equip}
onUse={use}
onClose={close}
/>
</container>
<text
loc={[54, 432]}
text={hint.value}
fillStyle="#8fb6ff"
alpha={hintAlpha.value}
/>
</container>
</container>
如果前面某一页的写法与本表冲突,以本表为准:左侧只有 Scroll 一个方案,selectedId 只有 null 一种空值,关闭只有面板一个入口。前面页面已经写过的坐标若与这里不同,按这里替换;本篇不再给第二个方案。
本表与最终骨架里的坐标都相对 720×480 根容器:面板主体矩形自己画在 [30, 30, 660, 420],标题 [54, 52] 直接相对根容器,不要再套一层 [30, 30] 的容器;否则标题会被再加一次偏移。
最终骨架里那层同尺寸的 container [0, 0, 720, 480] 是面板根:外层是画布根,里层是面板根(实际代码用 hidden 控制开合)。新内容加到面板根这一层,不要加到画布根上;两层的 loc 相同,所以坐标写法不变,但层级职责分开。
注册与打开
InventoryPanel 与 GameUI 在同一个文件里导出:
// inventory-panel.tsx:把名字与组件绑成一个对象
import { GameUI } from '@motajs/system';
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
src/client/ui/index.ts 再统一导出,打开处只认这个对象:
// src/client/ui/index.ts
export { InventoryUI } from './inventory/inventory-panel';
打开时把对象交给控制器,返回值就是这次打开的实例:
// 从主 UI 栈打开
const instance = props.state.mainUIController.open(InventoryUI, {});
// 关闭时把同一个实例交回去(面板内部用 props.instance 拿到它)
props.state.mainUIController.close(instance);
打开时传的是 GameUI 对象本身,名字不参与查找;构造与命名的规则见第 1 篇「UI 通用模板」。
关闭当前面板、马上打开另一个面板时,用 props.controller.keep() 包住切换,用完调用 safelyUnload(),避免背景闪一下;用法见「UI 系统」的「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 篇「显示开关」与「UI 系统」的「隐藏与显示」。
运行效果
下面是完整面板的 live:网格、详情、滚动、装备 / 使用、关闭与动画都在。关闭后可以用「重新打开」按钮回到面板。
渲染示例需要浏览器环境。 <script setup> import RenderDemo from '../../.vitepress/components/renderDemo.vue'; const fullLoader = () => import('../../.vitepress/components/demos/ui/inventory-6-full.tsx'); </script>边界与注意
- 动画在卸载后必须停。
onUnmounted里调用cancelAnimationFrame,不要只停一次。 - 动画节点不要进入子组件的 props 链。只改面板自己节点的
alpha,数据流保持单向。 - 拆分后 Props 要逐层传。不要用全局变量绕过父子关系,否则读者无法从文件结构看出数据流。
- 注册只是把名字和组件绑成一个对象,不写入名字查找表。不要按名字取 UI,也不要做全局注册表。
- 最终 live 如果跑不起来,保留代码与说明,不要删内容;先确认真实客户端环境与依赖是否齐全。
- 性能建议先测再改。
hidden、Scroll、key与组件粒度是四条固定口径,不要为了「看起来更快」额外加缓存。