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

13 KiB
Raw Blame History

示例(一)目标与骨架

前面五批讲的是零件:模板、元素、响应式、事件、组件、内置组件与 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 像素,不会压住网格。