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

203 lines
9.4 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.
# 示例(三)详情区
上一篇左侧已经能选道具,右侧还是占位。本篇把 `ItemDetail` 填上:名称、数量、描述,以及没有选中时的提示。
## 前置知识
阅读本篇前,建议先读完:
- [示例(二)道具网格](./inventory-example-2-grid.md)
- [文字](../basics/text.md)
- [通用参数](../basics/common-props.md)
## 详情区接的是哪个状态
详情不自己保存状态,它只接收一个「选中项」。选中项在 `InventoryPanel` 里用 `computed` 从 `items` 与 `selectedId` 算出来:
```tsx
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` 的根容器与区域同尺寸,内部再分四块:
```text
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:右侧面板
```tsx
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` 直接传给详情,详情不再查一遍列表:
```tsx
// 面板的右侧区域:坐标与最终布局一致
<container loc={[470, 100, 196, 280]}>
<ItemDetail
item={selectedItem.value}
onClear={() => (selectedId.value = null)}
/>
</container>
```
这条链与上一篇的点击上报是同一个方向的两端:
```text
点击 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` 的真实写法——两者不是同一段代码。
<ClientOnly>
<RenderDemo :loader="detailLoader" :width="720" :height="480" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
<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`,也不要在详情里重复查列表。