Files
template/docs/render-guide/advanced/inventory-example-1-skeleton.md
T

208 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 示例(一)目标与骨架
前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 UI 栈。这一批把它们装成同一个能用的面板——一个背包 / 装备界面。六篇按「每一步只加一小段」推进,本篇先定目标、拆分与骨架。
## 前置知识
阅读本篇前,建议先读完:
- [第一个静态界面](../basics/first-static-ui.md)
- [容器与坐标](../basics/container-and-coordinates.md)
## 这一步要解决什么
最终面板是一块 720×480 的区域:
- 顶部是标题与关闭按钮。
- 左侧是 5 列的道具网格,格子显示名称与数量。
- 右侧是选中道具的详情,没有选中时显示提示。
- 底部是装备 / 使用 / 关闭按钮。
- 道具变多后,左侧网格可以滚动。
本篇只做外框、标题、关闭按钮与左右两个占位区。网格、详情、滚动、交互与动画留到后面五篇,每一步都在这份骨架上继续填,不另起一套实现。
先搭骨架、后填数据,是因为骨架决定了每个后续节点「挂在哪里」:左侧区域有多大,网格就知道自己的行列要按什么尺寸排;右侧区域在哪,详情就知道自己该占多少文字宽度;底部操作条从哪开始,滚动区才不会压到按钮上。如果先写数据再回头调坐标,读者每加一步都要重新算一遍布局,最后也很难说清某一行代码到底属于树上的哪一层。
## 骨架在渲染树里的位置
先把最终面板的节点定下来,后面每一步都往这棵树里加东西。根 `container` 下依次是画布底色、面板主体、标题、关闭按钮、左侧占位与右侧占位,它们都是兄弟节点;树形规则本身见[第 2 篇「容器与坐标」](../basics/container-and-coordinates.md#渲染树根容器与子元素)。
三个区域是根容器的子容器,彼此是兄弟关系。它们的坐标都相对根容器的左上角:
- 面板主体在 `[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 篇「层级、变换与性能」](../basics/layer-transform-performance.md#渲染树层级与绘制顺序)。
## 组件与文件怎么分
组件拆分在骨架阶段就定下来,后面只往对应文件里填内容,不再改结构:
| 文件 | 导出 | 职责 | 主要 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`,替换时只改子树,不动坐标。
## 打开、状态与关闭归谁
面板由控制器打开,打开时创建实例;关闭时把实例交回同一个控制器:
```tsx
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` 先给外框、标题、关闭按钮与两个占位区:
```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 栈在创建实例时注入,作者不需要手动传。
## 打开它
骨架写完后,从三个常见位置打开:
```tsx
// 场景 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-system.md)。本篇先把打开入口跑通;从示例(六)开始统一用主 UI 栈打开,并在那里说明注册与栈的关系。
## 运行效果
下面是骨架的 live。它只包含面板本身;关闭按钮在 live 里只显示一行提示——文档站没有真实的 UI 栈,无法真的关闭面板。
<ClientOnly>
<RenderDemo :loader="skeletonLoader" :width="720" :height="480" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
<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 像素,不会压住网格。