13 KiB
示例(一)目标与骨架
前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 UI 栈。这一批把它们装成同一个能用的面板——一个背包 / 装备界面。六篇按「每一步只加一小段」推进,本篇先定目标、拆分与骨架。
前置知识
阅读本篇前,建议先读完:
这一步要解决什么
最终面板是一块 720×480 的区域:
- 顶部是标题与关闭按钮。
- 左侧是 5 列的道具网格,格子显示名称与数量。
- 右侧是选中道具的详情,没有选中时显示提示。
- 底部是装备 / 使用 / 关闭按钮。
- 道具变多后,左侧网格可以滚动。
本篇只做外框、标题、关闭按钮与左右两个占位区。网格、详情、滚动、交互与动画留到后面五篇,每一步都在这份骨架上继续填,不另起一套实现。
先搭骨架、后填数据,是因为骨架决定了每个后续节点「挂在哪里」:左侧区域有多大,网格就知道自己的行列要按什么尺寸排;右侧区域在哪,详情就知道自己该占多少文字宽度;底部操作条从哪开始,滚动区才不会压到按钮上。如果先写数据再回头调坐标,读者每加一步都要重新算一遍布局,最后也很难说清某一行代码到底属于树上的哪一层。
骨架在渲染树里的位置
先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 container 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见第 2 篇「容器与坐标」。
三个区域是根容器的子容器,彼此是兄弟关系。它们的坐标都相对根容器的左上角:
- 面板主体在
[30, 30],尺寸660×420,所以内容可用范围是x从 30 到 690、y从 30 到 450。 - 左侧区域
[54, 100, 400, 280],右边界 454;右侧区域[470, 100, 196, 280],两者之间留 16 像素空隙。 - 底部操作条在示例(五)加到
[54, 392, 304, 32]:左侧区域的下边界是100 + 280 = 380,操作条从 392 开始,380 < 392,两者不重叠。
720×480 是 UI 的逻辑尺寸,不是浏览器窗口尺寸。UI 被缩放显示时会按逻辑坐标整体变换,所以坐标只需要按 720×480 算一次,不必为不同窗口大小写几套。
它和第 2 篇说的「画布设计尺寸」是同一件事的两层:props.state.renderer.width / height 是客户端配置的画布尺寸(示例站点是 480×320),面板根容器再在这个画布上按自己的 loc 定位。面板根占多大、是否铺满,由你写的 loc 决定;示例写 [0, 0, 720, 480],所以它相对 UI 容器从左上角开始。画布比面板小时,超出的部分不会自动缩小或居中;需要适配不同窗口时,读 renderer.width / height 自己算位置。
分工可以记成一句:面板内部坐标一律相对面板根(示例按 720×480 设计),画布尺寸只决定面板根放在哪、最终如何缩放。先把面板当成固定设计稿写坐标,再在打开处按画布适配。
跑起来的方式不在本系列重复,见仓库根目录的 dev.md。示例站画布是 480×320,720×480 的面板超出画布的部分不会自动缩放,只会不可见;先按画布尺寸调面板根,或整体缩放。
第一次在示例站(480×320)验证时,不用重排内部坐标:给面板根加 scale={[2 / 3, 2 / 3]}(比例取 min(480 / 720, 320 / 480)),loc 仍写 [0, 0, 720, 480],整棵树会按同一比例缩小并完整落在 480×320 里。确认画面之后,如果要正式适配不同窗口,再按 renderer.width / height 改根 loc 并重排内部区域;不要同时改内部坐标和加缩放,否则会缩两次。
同一父级下的遮挡按 zIndex 与加入顺序决定:关闭按钮画在面板主体之后,因此会盖在主体上,点击落在按钮矩形里就由它接收。完整层级规则见第 7 篇「层级、变换与性能」。
组件与文件怎么分
组件拆分在骨架阶段就定下来,后面只往对应文件里填内容,不再改结构:
| 文件 | 导出 | 职责 | 主要 props |
|---|---|---|---|
inventory-panel.tsx |
InventoryPanel |
根容器、标题、关闭按钮、左右分栏与共享状态 | controller / instance / state |
item-grid.tsx |
ItemGrid |
按行列排出道具网格,把点击事件交回父组件 | items / selectedId / equippedId / onSelect |
item-cell.tsx |
ItemCell |
单个道具格子:背景、名称、数量、选中态 | item / selected / equipped / size |
item-detail.tsx |
ItemDetail |
右侧详情:名称、数量、描述与未选中提示 | item / onClear |
action-bar.tsx |
ActionBar |
底部按钮:装备 / 使用 / 关闭 | canEquip / canUse / equipped / 三个回调 |
表里列的是最终 props;equipped / equippedId 在示例(五)加入,前面几篇的格子先只有 selected。InventoryPanel 是唯一被 GameUI 注册的组件;另外四个都是普通子组件,由它按需组合。这样拆分的好处是:每个文件的职责固定,读者可以按文件名找到对应代码,而不用在一个大文件里翻找。
表里的「三个回调」「onSelect」「onClear」是父级写给子组件的监听器名;子组件内部用 emits: ['select'] 或 emits: ['clear'] 声明,再 emit('select', id) 触发,父级仍写 onSelect={...}。所以照表里的 props 名写父级用法即可,子组件内部则按 emits 声明。
本篇只落地 inventory-panel.tsx。左侧与右侧先写成两个带背景的 container 占位,不 import 后四个文件——这样每一步都能单独编译,等示例(二)(三)再把占位换成真正的 ItemGrid 与 ItemDetail,替换时只改子树,不动坐标。
打开、状态与关闭归谁
面板由控制器打开,打开时创建实例;关闭时把实例交回同一个控制器:
import { GameUI } from '@motajs/system';
// 构造只是把名字与组件绑成一个对象
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
// 从游戏主 UI 栈打开,返回值就是这次打开的实例
const instance = props.state.mainUIController.open(InventoryUI, {});
// 关闭时把同一个实例交回去
props.state.mainUIController.close(instance);
面板内部拿到的 props.instance 就是打开时创建的那个实例,props.controller 是打开它的控制器。所以面板自己关闭自己时,写的是 props.controller.close(props.instance),不需要记住是哪个控制器打开的。
关闭归 InventoryPanel。标题栏的关闭按钮调用这个方法;后面加进来的 ActionBar 只发出 close 事件,由面板决定是否关闭。子组件不直接拿 controller 去关面板,否则同一件事会出现两个入口,按键关闭和按钮关闭的行为也会分叉。
状态归 InventoryPanel。items 与 selectedId 由面板持有,网格只负责显示与上报点击,详情只接收派生结果。本篇先把关闭按钮接通,items 与 selectedId 从示例(二)开始填。
骨架代码
inventory-panel.tsx 先给外框、标题、关闭按钮与两个占位区:
import { defineComponent } from 'vue';
import { GameUI, SetupComponentOptions } from '@motajs/system';
import { DefaultProps } from '@motajs/render-vue';
import { IGameUIPropsBase } from '@user/client-base';
// UI 的 Props 必须同时继承基础 Props 与默认 Props
interface InventoryPanelProps extends IGameUIPropsBase, DefaultProps {}
const inventoryPanelProps = {
// 三个键少一个,组件里就拿不到对应的值
props: ['controller', 'instance', 'state']
} satisfies SetupComponentOptions<InventoryPanelProps>;
const InventoryPanel = defineComponent<InventoryPanelProps>(props => {
// 关闭归面板:把当前实例交回打开它的控制器
const close = () => {
props.controller.close(props.instance);
};
return () => (
<container loc={[0, 0, 720, 480]}>
{/* 画布底色 */}
<g-rect loc={[0, 0, 720, 480]} fill fillStyle="#0e141b" />
{/* 面板主体 */}
<g-rectr
loc={[30, 30, 660, 420]}
circle={[18]}
fill
fillStyle="#1d2b45"
stroke
strokeStyle="#2f6fed"
/>
<text loc={[54, 52]} text="背包" fillStyle="#e8f0ff" />
{/* 关闭按钮必须在骨架阶段就能用,否则后面每加一块内容都无法验证退出 */}
<container loc={[626, 50, 56, 32]} onClick={close}>
<g-rectr
loc={[0, 0, 56, 32]}
circle={[8]}
fill
fillStyle="#7a3d3d"
/>
<text loc={[14, 8]} text="关闭" fillStyle="#ffe9e9" />
</container>
{/* 左侧网格占位:示例(二)换成 ItemGrid */}
<container loc={[54, 100, 400, 280]}>
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="道具网格占位" fillStyle="#8fb6ff" />
</container>
{/* 右侧详情占位:示例(三)换成 ItemDetail */}
<container loc={[470, 100, 196, 280]}>
<g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
<text loc={[16, 16]} text="详情占位" fillStyle="#8fb6ff" />
</container>
</container>
);
}, inventoryPanelProps);
export const InventoryUI = new GameUI('inventory-panel', InventoryPanel);
这段代码只做三件事:画出 720×480 的面板、放好标题与关闭按钮、用两个占位容器标出后续网格与详情的位置。
在渲染树上,根 container 是这次 UI 的入口,面板主体、标题、关闭按钮与两个占位区都是它的直接子元素。关闭按钮自己又是一个小容器,内部只有底板与文字:点击命中按钮区域后,事件交给带 onClick 的容器,调用 close,再由控制器卸载实例。两个占位容器不是装饰,它们先把区域尺寸写进树里,后面换 ItemGrid 与 ItemDetail 时只需要替换子节点,坐标不用重算。
props 数组必须同时列出 controller、instance、state,少一个组件里就拿不到对应的值。InventoryPanel 被 GameUI 注册后,这三个值由 UI 栈在创建实例时注入,作者不需要手动传。
打开它
骨架写完后,从三个常见位置打开:
// 场景 UI:由客户端核心的场景控制器打开
props.state.sceneController.open(InventoryUI, {});
// 在另一个 UI 内打开:沿用当前 UI 的控制器
props.controller.open(InventoryUI, {});
// 游戏内的背包通常从主 UI 栈打开
props.state.mainUIController.open(InventoryUI, {});
三者的区别只在「由哪个控制器管理这次打开的实例」:mainUIController 管主界面栈,sceneController 管场景层,props.controller 是当前 UI 的控制器。具体差别见「UI 系统」。本篇先把打开入口跑通;从示例(六)开始统一用主 UI 栈打开,并在那里说明注册与栈的关系。
运行效果
下面是骨架的 live。它只包含面板本身;关闭按钮在 live 里只显示一行提示——文档站没有真实的 UI 栈,无法真的关闭面板。
渲染示例需要浏览器环境。 <script setup> import RenderDemo from '../../.vitepress/components/renderDemo.vue'; const skeletonLoader = () => import('../../.vitepress/components/demos/ui/inventory-1-skeleton.tsx'); </script>边界与注意
- 组件拆分在骨架阶段就定下来,后面只填内容。中途换结构会让读者无法把前几篇和后几篇对上。
- 不用真实素材。图标一律用
g-rect/g-rectr加text画出来,读者不需要准备图片。 - 关闭按钮必须在骨架阶段就能用。否则后面每加一块内容,都无法验证「面板能不能正常退出」。
- 不要把网格、详情、按钮全塞进
InventoryPanel。根组件只负责布局与共享状态,具体区域交给子组件。 - Props 只能用
IGameUIPropsBase配DefaultProps,props数组至少包含controller、instance、state。 - 两个占位区按最终布局给足尺寸:左侧
[54, 100, 400, 280]、右侧[470, 100, 196, 280]。示例(五)的操作条从y = 392开始,和左侧区域的下边界 380 之间留了 12 像素,不会压住网格。