13 KiB
示例(二)道具网格
上一篇的左侧只有一块占位。本篇把道具数据、ItemCell 与 ItemGrid 填进去,让网格能显示、能选中。
前置知识
阅读本篇前,建议先读完:
从占位到网格
本步只替换左侧占位区,右侧详情与底部操作条仍然是占位:
container [54, 100, 400, 280] 左侧区域
├─ g-rect 区背景
└─ ItemGrid 本步新增的组件
├─ ItemCell 第 1 个道具
├─ ItemCell 第 2 个道具
└─ ... 按行列排开
网格挂在左侧区域里,坐标相对左侧容器,不再相对根容器。这样后面换滚动容器、调整左侧区域大小时,网格跟着区域走,不用改每个格子的绝对坐标。
数据模型:Item 只定义一次
背包里的道具用一个最小模型表示。这个 Item 只在示例(二)定义一次,示例(三)到(六)都直接引用它,不各自重写:
// 道具模型: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'。类型导入编译后会被擦除,不会引入运行时循环依赖。
假数据只在写作示范里用,读者可以替换成自己的存档数据:
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:
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 不写死每个格子的坐标,而是用列数、格子尺寸与间距算出位置:
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,不直接读父级闭包。
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 也放在面板:详情与操作按钮都要用它,放在父级只有一份,不会出现网格与详情各算一遍、结果不一致。
点击如何上报
一次点击经过三层,每层只做自己的事:
点击 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 在骨架上加了网格与选中态。点击任意格子,右侧占位区会显示当前选中的道具。
渲染示例需要浏览器环境。 <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。