Files
template/docs/render-guide/advanced/inventory-example-3-detail.md

9.4 KiB
Raw Permalink Blame History

示例(三)详情区

上一篇左侧已经能选道具,右侧还是占位。本篇把 ItemDetail 填上:名称、数量、描述,以及没有选中时的提示。

前置知识

阅读本篇前,建议先读完:

详情区接的是哪个状态

详情不自己保存状态,它只接收一个「选中项」。选中项在 InventoryPanel 里用 computed 从 items 与 selectedId 算出来:

import { computed, ref } from 'vue';

// 面板持有选中 id;未选中用 null,不用 undefined 或空字符串
const selectedId = ref<string | null>(null);

// 选中项由 items 与 selectedId 派生;找不到时统一变成 null
const selectedItem = computed(
    () => items.value.find(item => item.id === selectedId.value) ?? null
);

selectedId 的类型是 ref<string | null>,初始值 null,表示「什么都没选」。用 null 而不是 undefined 或空字符串,是因为三种「没有值」的写法会在不同地方产生不同行为:undefined 容易被当成「还没传」而被默认值替换,空字符串会被当成一个合法 id 去查列表。null 在类型上明确表示「有值,但值是空」。

find 找不到时返回 undefined,这里用 ?? null 收口,让 selectedItem 的类型固定为 Item | null。这样详情组件只需要判断「有没有 item」,不用区分 undefined 与 null 两种空值。

详情区的树结构

详情区在面板右侧,最终布局是 [470, 100, 196, 280]。ItemDetail 的根容器与区域同尺寸,内部再分四块:

container [0, 0, 196, 280]        详情组件根
├─ g-rect                          区背景
├─ text [16, 16]                   小标题「详情」
├─ container hidden={有选中}        未选中提示
│  └─ text [16, 52]                「请选择道具」
├─ container hidden={没选中}        详情内容
│  ├─ text [16, 52]                名称
│  ├─ text [16, 84]                数量
│  └─ TextContent [16, 120]        描述,按宽度折行
└─ container [16, 236, 164, 28]    取消选择按钮

名称、数量、描述都是详情容器的子节点,位置相对详情根容器。描述没有用 text 元素硬排:text 只画一行,不会自动换行;TextContent 给了 width 才会按宽度折行,autoHeight 让高度跟着内容走。width 是必填项,不传时组件拿不到排版宽度。描述从 y = 120 开始,到取消选择按钮上方 236 为止,大约能放四到五行;更长的说明要么缩短文案,要么在详情内部再套一个 Scroll,不要让它盖住按钮。

hidden 的两块是兄弟节点,同一时刻只有一块参与绘制与命中:未选中时提示可见,选中时详情内容可见。hidden 不显示、不交互,但元素与状态仍在,不会因为频繁切换选中而反复创建、销毁子树。

ItemDetail:右侧面板

import { defineComponent } from 'vue';
import { SetupComponentOptions } from '@motajs/system';
import { DefaultProps } from '@motajs/render-vue';
import { TextContent } from '@user/client-base';

interface ItemDetailProps extends DefaultProps {
    // 没有选中时是 null,组件必须允许空值
    item: Item | null;
}

interface ItemDetailEmits {
    clear: () => void;
}

const itemDetailProps = {
    props: ['item'],
    emits: ['clear']
} satisfies SetupComponentOptions<
    ItemDetailProps,
    ItemDetailEmits,
    keyof ItemDetailEmits
>;

const ItemDetail = defineComponent<
    ItemDetailProps,
    ItemDetailEmits,
    keyof ItemDetailEmits
>((props, { emit }) => {
    return () => (
        <container loc={[0, 0, 196, 280]}>
            <g-rect loc={[0, 0, 196, 280]} fill fillStyle="#101820" />
            <text loc={[16, 16]} text="详情" fillStyle="#8fb6ff" />

            {/* 没有选中:显示提示 */}
            <container hidden={props.item !== null}>
                <text loc={[16, 52]} text="请选择道具" fillStyle="#4f6d94" />
            </container>

            {/* 有选中:显示名称、数量与描述。两块都渲染,用 hidden 切换 */}
            <container hidden={props.item === null}>
                <text
                    loc={[16, 52]}
                    text={props.item?.name ?? ''}
                    fillStyle="#e8f0ff"
                />
                <text
                    loc={[16, 84]}
                    text={`数量:${props.item?.count ?? 0}`}
                    fillStyle="#cfe0ff"
                />
                {/* 长描述用 TextContent;width 必填,autoHeight 让高度跟着内容走 */}
                <TextContent
                    loc={[16, 120]}
                    width={164}
                    text={props.item?.desc ?? ''}
                    autoHeight
                    fill
                    fillStyle="#8fb6ff"
                />
            </container>

            {/* 回到未选中:详情只上报,不自己改父级状态 */}
            <container loc={[16, 236, 164, 28]} onClick={() => emit('clear')}>
                <g-rectr
                    loc={[0, 0, 164, 28]}
                    circle={[6]}
                    fill
                    fillStyle="#33465f"
                />
                <text loc={[12, 6]} text="取消选择" fillStyle="#e8f0ff" />
            </container>
        </container>
    );
}, itemDetailProps);

export { ItemDetail };

在渲染树上,ItemDetail 的根是右侧区域的整块容器,背景是第一个子节点,保证后面所有文字都画在背景之上;取消选择按钮是最后一个子节点,因此盖在其他内容之上,不会被描述文字挡住。按钮只发出 clear 事件,不碰 selectedId——选中状态归面板,详情没有写权限。

这里用 hidden 而不是三元,是因为选中切换很频繁,两块内容都很轻,保留元素后不需要反复创建与销毁。等读者真的需要「每次切换都重置」时,再换成三元。

选中态如何流到详情

面板把派生的 selectedItem 直接传给详情,详情不再查一遍列表:

// 面板的右侧区域:坐标与最终布局一致
<container loc={[470, 100, 196, 280]}>
    <ItemDetail
        item={selectedItem.value}
        onClear={() => (selectedId.value = null)}
    />
</container>

这条链与上一篇的点击上报是同一个方向的两端:

点击 ItemCell → ItemGrid → 面板写 selectedId
  → selectedItem 重算 → ItemDetail 收到新的 item
点击「取消选择」→ ItemDetail 发 clear → 面板把 selectedId 写回 null
  → selectedItem 变成 null → 详情显示「请选择道具」

详情不要在组件内部再 items.find(...):那会让列表出现两份查询逻辑,一份用 selectedId,一份用内部状态,两边一旦不同步,就会出现「左侧高亮 A、右侧显示 B」。派生只做一次,放在持有源状态的面板里。

空态与边界

三种情况都要给出显示与恢复方式:

情况 详情显示 如何恢复
未选中 「请选择道具」 点任意格子,或初始状态就是空
选中项被删除 find 返回 undefined,收口成 null 点其他格子;不要留着旧 id 高亮
items 为空 与未选中相同 先获得道具,再打开面板

未选中不是错误状态,而是面板的初始状态。示例(二)里 selectedId 的初始值是 null,所以第一次打开面板时右侧就显示提示;点击格子后才第一次出现详情。

「选中项被删除」要在面板层处理:删除道具时同时检查 selectedId.value === 被删的 id,如果是就把 selectedId 写回 null。只在详情里判空、不清理面板的 id,会让 selectedId 指向一个不存在的道具,之后任何按 id 比较的逻辑都会失效。

运行效果

下面的 live 选中不同格子,右侧详情随之更新;点「取消选择」可以看到没有选中时的提示。live 用元素层的 text 等价展示多行说明,正文代码块才给出 TextContent 的真实写法——两者不是同一段代码。

渲染示例需要浏览器环境。 <script setup> import RenderDemo from '../../.vitepress/components/renderDemo.vue'; const detailLoader = () => import('../../.vitepress/components/demos/ui/inventory-3-detail.tsx'); </script>

边界与注意

  • computed 里不要写副作用。它只负责算值,需要「变化后做一件事」时用 watch。
  • find 找不到时返回 undefined,用 ?? null 收口;详情组件的 item 要允许为 null。
  • TextContent 的 width 必填。不给宽度时文字不会按预期折行,autoHeight 也失去意义。
  • 两块都渲染时注意 zIndex 与遮挡。提示层不要盖住真正的详情,也不要在有选中时仍然拦截点击。
  • 选中态放在父组件,详情只接收结果。子组件不要自己再存一份 selectedId,也不要在详情里重复查列表。