Files
template/docs/render-guide/advanced/inventory-example-2-grid.md

307 lines
13 KiB
Markdown
Raw Permalink 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.
# 示例(二)道具网格
上一篇的左侧只有一块占位。本篇把道具数据、`ItemCell` 与 `ItemGrid` 填进去,让网格能显示、能选中。
## 前置知识
阅读本篇前,建议先读完:
- [示例(一)目标与骨架](./inventory-example-1-skeleton.md)
- [基础图形](../basics/basic-shapes.md)
## 从占位到网格
本步只替换左侧占位区,右侧详情与底部操作条仍然是占位:
```text
container [54, 100, 400, 280] 左侧区域
├─ g-rect 区背景
└─ ItemGrid 本步新增的组件
├─ ItemCell 第 1 个道具
├─ ItemCell 第 2 个道具
└─ ... 按行列排开
```
网格挂在左侧区域里,坐标相对左侧容器,不再相对根容器。这样后面换滚动容器、调整左侧区域大小时,网格跟着区域走,不用改每个格子的绝对坐标。
## 数据模型:Item 只定义一次
背包里的道具用一个最小模型表示。这个 `Item` 只在示例(二)定义一次,示例(三)到(六)都直接引用它,不各自重写:
```tsx
// 道具模型:id 用于选中与装备状态,其余字段用于显示
interface Item {
id: string;
name: string;
count: number;
desc: string;
}
```
`id` 用来判断选中与装备状态,必须是稳定且唯一的值。不要用数组下标代替:下标会随着删除、排序变化,同一个道具换到另一个位置后就变成了另一个身份。
示例把这个 `interface Item` 与 `ItemGrid` 放在 `item-grid.tsx` 里并 `export`;使用它的文件写 `import type { Item } from './item-grid'`。类型导入编译后会被擦除,不会引入运行时循环依赖。
假数据只在写作示范里用,读者可以替换成自己的存档数据:
```tsx
const items = ref<Item[]>([
{ id: 'potion-red', name: '红药水', count: 3, desc: '恢复少量生命。' },
{ id: 'potion-blue', name: '蓝药水', count: 1, desc: '恢复少量魔力。' },
{ id: 'key-yellow', name: '黄钥匙', count: 5, desc: '打开黄色的门。' },
{ id: 'key-blue', name: '蓝钥匙', count: 2, desc: '打开蓝色的门。' },
{ id: 'sword-wood', name: '木剑', count: 1, desc: '最基础的武器。' },
{ id: 'shield-wood', name: '木盾', count: 1, desc: '最基础的防具。' },
{ id: 'gem-red', name: '红宝石', count: 4, desc: '镶嵌用的素材。' },
{ id: 'gem-blue', name: '蓝宝石', count: 2, desc: '镶嵌用的素材。' },
{ id: 'scroll', name: '回城卷轴', count: 1, desc: '回到起点。' },
{ id: 'bread', name: '面包', count: 6, desc: '恢复少量生命。' }
]);
```
`items` 是 `ref<Item[]>`,由 `InventoryPanel` 持有。用 `ref` 而不是普通数组,是因为后面使用道具会改数量、面板关闭后可能重新打开,数组需要在多次渲染之间保持同一份响应式数据。子组件不在自己的闭包里引用 `items`,只通过 props 拿到解包后的数组。
## 网格的树结构
网格是两层:`ItemGrid` 是容器,负责算位置;`ItemCell` 是叶子,负责画一个格子。一个格子在外层包一个定位容器,把「第几行第几列」换算成坐标,`ItemCell` 自己的根元素仍然固定在 `[0, 0]`,内部只按尺寸画。
5 列示例的坐标来源:
- 列宽 `cellSize = 66`,间距 `gap = 8`,所以列与列之间隔 74。
- 第 `index` 个道具的列是 `index % 5`,行是 `Math.floor(index / 5)`。
- 横坐标 `x = col * (66 + 8)`,纵坐标 `y = row * (66 + 8)`。
- 5 列总宽 `5 * 66 + 4 * 8 = 362`,放在 400 宽的左侧区域里还剩 38 像素。
格子是并列的兄弟节点,绘制与命中按同一父级下的顺序进行;每格的位置互不重叠,所以点击落在哪个矩形里就由哪个格子接收。
## ItemCell:一个格子
格子只需知道「显示哪个道具」「是否选中」「多大」,点击时把 id 交回父组件。写法沿用[自定义组件的 props](./custom-components.md#props):
```tsx
import { defineComponent } from 'vue';
import { SetupComponentOptions } from '@motajs/system';
import { DefaultProps } from '@motajs/render-vue';
interface ItemCellProps extends DefaultProps {
item: Item;
selected?: boolean;
size?: number;
}
interface ItemCellEmits {
select: (id: string) => void;
}
const itemCellProps = {
props: ['item', 'selected', 'size'],
emits: ['select']
} satisfies SetupComponentOptions<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>;
const ItemCell = defineComponent<
ItemCellProps,
ItemCellEmits,
keyof ItemCellEmits
>((props, { emit }) => {
// 格子不保存状态,只根据 item 与 selected 渲染
// 尺寸在面板生命周期内不变,读一次即可;若尺寸会随窗口变化,再改成 computed
const size = props.size ?? 66;
return () => (
<container
loc={[0, 0, size, size]}
onClick={() => emit('select', props.item.id)}
>
<g-rectr
loc={[0, 0, size, size]}
circle={[10]}
fill
fillStyle={props.selected ? '#2f6fed' : '#26364d'}
/>
{/* 选中时加一圈描边;未选中时用暗色边框保持尺寸一致 */}
<g-rectr
loc={[1, 1, size - 2, size - 2]}
circle={[9]}
stroke
strokeStyle={props.selected ? '#f2b84b' : '#33465f'}
/>
{/* 名称在左上角,数量固定在左下角 */}
<text loc={[8, 10]} text={props.item.name} fillStyle="#ffffff" />
<text
loc={[8, size - 24]}
text={`× ${props.item.count}`}
fillStyle="#cfe0ff"
/>
</container>
);
}, itemCellProps);
export { ItemCell };
```
在渲染树上,`ItemCell` 的根是一个带尺寸的容器,背景、描边、名称、数量都是它的子元素。它没有内部状态,`selected` 由父级传入:父级改变 `selectedId` 后,每个格子重新计算自己该不该高亮,不会出现「一个格子还亮着」的残留。这也是为什么点击不自己改状态,而是 `emit('select', props.item.id)` 交回父级。
## ItemGrid:按行列排列
`ItemGrid` 不写死每个格子的坐标,而是用列数、格子尺寸与间距算出位置:
```tsx
import { computed, defineComponent } from 'vue';
import { SetupComponentOptions } from '@motajs/system';
import { DefaultProps } from '@motajs/render-vue';
interface ItemGridProps extends DefaultProps {
items: Item[];
selectedId: string | null;
columns?: number;
cellSize?: number;
gap?: number;
}
interface ItemGridEmits {
select: (id: string) => void;
}
const itemGridProps = {
props: ['items', 'selectedId', 'columns', 'cellSize', 'gap'],
emits: ['select']
} satisfies SetupComponentOptions<
ItemGridProps,
ItemGridEmits,
keyof ItemGridEmits
>;
const ItemGrid = defineComponent<
ItemGridProps,
ItemGridEmits,
keyof ItemGridEmits
>((props, { emit }) => {
// 列数、尺寸、间距都可能来自 props,用 computed 派生,变化时重算
const columns = computed(() => props.columns ?? 5);
const cellSize = computed(() => props.cellSize ?? 66);
const gap = computed(() => props.gap ?? 8);
return () => (
// 网格根容器与左侧区域同尺寸,只做分组与定位,不裁切内容
<container loc={[0, 0, 400, 280]}>
{props.items.map((item, index) => {
// 每行放 columns 个,超出后换到下一行
const col = index % columns.value;
const row = Math.floor(index / columns.value);
const x = col * (cellSize.value + gap.value);
const y = row * (cellSize.value + gap.value);
return (
// 定位容器与格子同尺寸,避免默认尺寸盖住邻居
<container
key={item.id}
loc={[x, y, cellSize.value, cellSize.value]}
>
<ItemCell
item={item}
selected={item.id === props.selectedId}
size={cellSize.value}
onSelect={id => emit('select', id)}
/>
</container>
);
})}
</container>
);
}, itemGridProps);
export { ItemGrid };
```
这里用 `.map()` 把数组映射成一组元素,没有写循环指令。定位容器与格子同尺寸,不会出现「容器默认 200×200 盖住邻格」的问题;容器本身没有点击监听,点击命中的是格子,再沿父链交给 `ItemGrid`。
`key` 用 `item.id`:格子身份跟道具走,不跟位置走。现在列表顺序固定、看起来用下标也能跑,但示例(五)会减数量、以后可能删除道具,一旦增删,下标会把「第 3 个位置」错当成「同一个道具」。从一开始就按 id 绑定,后面不用返工。
## 数据如何进入网格
数据只有一条路:`InventoryPanel` 持有 `items`,把解包后的数组传给 `ItemGrid`;`ItemGrid` 把它映射成若干 `ItemCell`;`ItemCell` 只接收 `item` 与 `selected`,不直接读父级闭包。
```tsx
import { computed, ref } from 'vue';
// 面板持有 items,子组件只接收解包后的数组
const items = ref<Item[]>([
/* 上面的假数据 */
]);
// 未选中用 null,不用 undefined 或空字符串
const selectedId = ref<string | null>(null);
// 选中项由 items 与 selectedId 派生,详情与按钮共用同一份数据
const selectedItem = computed(
() => items.value.find(item => item.id === selectedId.value) ?? null
);
<container loc={[54, 100, 400, 280]}>
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
{/* 网格只上报点击,选中值仍由父组件保存 */}
<ItemGrid
items={items.value}
selectedId={selectedId.value}
columns={5}
cellSize={66}
gap={8}
onSelect={id => (selectedId.value = id)}
/>
</container>;
```
`items` 作为 prop 传的是 `items.value`,也就是数组本身;`ItemGrid` 内部收到的是普通数组,不需要再解包。派生数据 `selectedItem` 也放在面板:详情与操作按钮都要用它,放在父级只有一份,不会出现网格与详情各算一遍、结果不一致。
## 点击如何上报
一次点击经过三层,每层只做自己的事:
```text
点击 ItemCell
→ ItemCell 的 onClick 发出 emit('select', item.id)
→ ItemGrid 的 onSelect 收到 id,再 emit('select', id)
→ InventoryPanel 的 onSelect 把 selectedId 写成这个 id
→ 重新渲染:选中格子高亮,selectedItem 重算
```
- `ItemCell` 知道「自己被点了」,但不知道该选谁,所以只上报自己的 `item.id`。
- `ItemGrid` 知道「网格里有一个 id 被选中」,但它不持有选中状态,继续上报。
- `InventoryPanel` 是唯一持有 `selectedId` 的地方,写值后由响应式系统把新状态推回子树。
这条链也是后面示例(四)滚动、示例(五)操作条继续沿用的路径:子组件上报,面板决定。
## 这一步的边界
本步的网格是普通容器平铺,不滚动。道具多到超出一屏时,超出的格子仍然会被渲染,只是画在区域外;`Scroll` 要等到示例(四)才引入,它会把「平铺 + 只渲染视口附近」接在这棵子树上。
所以不要把本步的普通网格当成最终方案。示例(四)会明确替换关系:左侧换成 `Scroll`,`ItemGrid` 的 props 与事件链不变,只把根容器换成滚动容器;示例(五)(六)不会再回到普通网格或 `ListPage`。
## 运行效果
下面的 live 在骨架上加了网格与选中态。点击任意格子,右侧占位区会显示当前选中的道具。
<ClientOnly>
<RenderDemo :loader="gridLoader" :width="720" :height="480" />
<template #fallback>
渲染示例需要浏览器环境。
</template>
</ClientOnly>
<script setup>
import RenderDemo from '../../.vitepress/components/renderDemo.vue';
const gridLoader = () =>
import('../../.vitepress/components/demos/ui/inventory-2-grid.tsx');
</script>
## 边界与注意
- 列宽与间距用常量算,不要手写每格坐标。格子数量变化时只改 `columns` 或 `cellSize`。
- 选中态只由 `selectedId` 决定,不要在格子里各存一份。否则父组件切换选中时会出现不同步。
- `.map()` 返回的每一项结构必须一致。定位容器与格子同尺寸,不要用默认尺寸的容器去套小格子。
- `id` 用稳定且唯一的值,`key` 也用 `item.id`;不要用数组下标代替。
- 网格区域尺寸变化时重新算列数,不要让最后一列溢出到详情区;本篇 5 列总宽 362,左侧区域宽 400。