11 KiB
示例(四)滚动与列表
道具少的时候,网格一次就能排下。道具变多后,左侧区域放不下,需要滚动。本篇把示例(二)的普通网格换成 Scroll,并说明这次替换在渲染树、事件与数据流上各自改了什么。
前置知识
阅读本篇前,建议先读完:
为什么要换滚动
普通容器只是按坐标把子元素画出来:区域外的格子照样绘制,超出的部分被窗口裁掉,但节点仍然在树上。道具只有十件时感觉不到问题;四十件时,左侧区域外的格子会越画越多,滚轮也没有任何反应。
Scroll 负责的是「视口」这一层:
- 它给内容一个固定大小的窗口,窗口外的行被隐藏(逻辑裁剪),不会继续绘制。
- 它自己处理滚轮、拖动与右侧滚动条,不需要作者再写
onWheel。 - 它按子元素的包围盒计算可滚动总长度,末尾用
padEnd补一段空白。
代价是限制:Scroll 只检查它的直接子元素,所以内容不能先包一个大容器再放进去。一个把全部格子包住的 ItemGrid 根容器会让虚拟滚动退化成「一整块内容」,只能整体显示或整体隐藏。
组件本身不是节点(第 13 篇):ItemGrid 返回的是行数组,这些行会平铺成父级 Scroll 的直接子元素,而不是躲在组件内部;所以行容器能被 Scroll 直接读到,虚拟滚动成立。
本步明确替换示例(二)的普通网格:左侧最终方案是 Scroll,示例(五)(六)不会再回到普通网格或 ListPage。
Scroll 在渲染树里的位置
替换后,左侧区域的树是这样:
container [54, 100, 400, 280] 左侧区域(坐标与最终布局一致)
├─ g-rect 区背景
├─ Scroll [0, 0, 372, 244] 视口:宽 372、高 244
│ ├─ 行容器 [0, 0, 362, 66] 第 1 行,Scroll 的直接子元素
│ │ ├─ ItemCell 第 1 个格子
│ │ └─ ... 同一行其余 4 个
│ ├─ 行容器 [0, 74, 362, 66] 第 2 行
│ └─ ... 按 74 的行距继续
├─ 按钮 [0, 252, 90, 28] 「回到顶部」
└─ 按钮 [100, 252, 90, 28] 「滚到底部」
Scroll 的根是左侧区域里的一个子容器,loc 的第三、四项就是视口大小。视口宽 372,左侧区域宽 400,右边留出的 28 像素是滚动条与内边距的位置;高度 244,下面从 252 开始放两个按钮,244 < 252,按钮不会被内容盖住。
滚动条是 Scroll 内部的一个 custom 节点,固定画在视口右侧、层级高于内容。作者不需要手动创建它,只需要把可点击的元素避开右侧滚动条区域。
未滚动时,Scroll 的内容容器从 [0, 0] 开始;滚动后,内容整体向上平移,但每个行容器在树上的 loc 不变。这就是为什么行坐标可以按「从内容顶部往下累计」来算:0, 74, 148, ...,而不用关心当前滚到了哪里。
Scroll 通过 ref 暴露两个方法:scrollTo(y, time?) 滚到指定位置,getScrollLength() 返回还能滚多长。ref<ScrollExpose>() 拿到的就是这个接口,只有在需要「回到顶部 / 滚到底部 / 滚到某一行」时才用它。
数据与选中态如何穿过滚动层
Scroll 只负责视口,不持有道具数据,也不持有选中状态:
items仍然是InventoryPanel里的ref<Item[]>,由面板传给ItemGrid。selectedId仍然是面板的ref<string | null>,由ItemGrid继续按 id 比较。ItemGrid的 props 链不变:items/selectedId/onSelect(示例(五)再加equippedId)。
唯一要改的是 ItemGrid 的根节点:示例(二)里它返回一个 container,现在改成返回「行容器数组」,让每一行直接成为 Scroll 的直接子元素。组件本身仍然是一个组件,只是它的子树从「一个容器」变成了「一组并列容器」:
// item-grid.tsx:根节点从单个 container 改成行容器数组
const ItemGrid = defineComponent<
ItemGridProps,
ItemGridEmits,
keyof ItemGridEmits
>((props, { emit }) => {
const columns = computed(() => props.columns ?? 5);
const cellSize = computed(() => props.cellSize ?? 66);
const gap = computed(() => props.gap ?? 8);
return () => {
const pitch = cellSize.value + gap.value;
const rowCount = Math.ceil(props.items.length / columns.value);
const rows = [];
for (let row = 0; row < rowCount; row++) {
const start = row * columns.value;
const cells = props.items.slice(start, start + columns.value);
rows.push(
// 一行是 Scroll 的一个直接子元素,行距由 loc 的 y 决定
<container
key={row}
loc={[0, row * pitch, 362, cellSize.value]}
>
{cells.map((item, col) => (
<container
key={item.id}
loc={[
col * pitch,
0,
cellSize.value,
cellSize.value
]}
>
<ItemCell
item={item}
selected={item.id === props.selectedId}
size={cellSize.value}
onSelect={id => emit('select', id)}
/>
</container>
))}
</container>
);
}
return rows;
};
}, itemGridProps);
行容器的 key 用行号,是因为行本身没有业务身份,只表示「第几行」;行内的格子 key 仍然用 item.id,身份跟道具走。滚动时 Scroll 按行容器的包围盒决定整行显示还是隐藏,所以一行的高度必须包住这一行的格子,不能只给格子高度却让行容器用默认 200×200。
面板里怎么接
面板把 ItemGrid 放进 Scroll,其余状态不变:
import { ref } from 'vue';
import { Scroll, ScrollExpose } from '@user/client-base';
// 面板里:滚动容器只包住网格,选中态仍由面板持有
const scroll = ref<ScrollExpose>();
// 回到顶部:scrollTo(目标位置, 动画时长)
const backToTop = () => {
scroll.value?.scrollTo(0, 200);
};
// 滚到底部:先取总长度,再滚过去
const toBottom = () => {
scroll.value?.scrollTo(scroll.value.getScrollLength(), 200);
};
<container loc={[54, 100, 400, 280]}>
<g-rect loc={[0, 0, 400, 280]} fill fillStyle="#101820" />
<Scroll ref={scroll} loc={[0, 0, 372, 244]} padEnd={16}>
<ItemGrid
items={items.value}
selectedId={selectedId.value}
columns={5}
cellSize={66}
gap={8}
onSelect={id => (selectedId.value = id)}
/>
</Scroll>
<container loc={[0, 252, 90, 28]} onClick={backToTop}>
<g-rectr loc={[0, 0, 90, 28]} circle={[6]} fill fillStyle="#2f6fed" />
<text loc={[10, 6]} text="回到顶部" fillStyle="#ffffff" />
</container>
<container loc={[100, 252, 90, 28]} onClick={toBottom}>
<g-rectr loc={[0, 0, 90, 28]} circle={[6]} fill fillStyle="#33465f" />
<text loc={[10, 6]} text="滚到底部" fillStyle="#e8f0ff" />
</container>
</container>;
padEnd 给内容末尾多留 16 像素,避免最后一行贴着视口底边时滚动条位置看起来不对。getScrollLength() 返回的是「内容总长减视口高度」,也就是最大可滚动距离;直接把它交给 scrollTo 就滚到底。
单位补在这里:scrollTo(y, time) 的 time 是毫秒,默认 0 表示立即跳转;padEnd 是像素,追加在内容总长度之后。
滚动位置保存在 Scroll 组件自己的状态里。面板被真正卸载(关闭)后,组件销毁,下次打开回到顶部;如果只是用 hide 暂时隐藏实例,位置会保留。两种行为都是合理的,取决于你要「每次都从头看」还是「回到上次的位置」。
滚动与事件
滚轮不需要作者处理:Scroll 在根容器上监听 onWheel,把滚动量换算成目标位置,再带动画滚过去。子元素上的点击仍然按渲染树命中:先落到格子,再沿父链交给 ItemGrid 与面板。
滚动容器在捕获阶段会给事件坐标补上当前滚动偏移,所以格子拿到的是自己在内容里的局部坐标,不会因为「已经滚了 300 像素」而算错点击位置。这一点对拖动与点击都成立。
拖动内容与点击格子共用同一套按下 / 移动 / 抬起事件。Scroll 在按下时记录内容位置,移动超过阈值才视为拖动;没有移动的按下与抬起仍然是一次点击,会正常上报选中。作者的注意事项只有两条:
- 不要在内容上再套一层自己的滚动手势,两套手势会互相抢事件。
- 可点击元素避开通往滚动条的右侧区域,滚动条本身会先接住那里的按下事件。
noevent 与 actionStroke 在这里都不是必需的:Scroll 已经处理了手势,格子按自身矩形命中即可。
为什么不用 ListPage 作为最终方案
ListPage 适合「左边一列文本、右边详情」的内置页面,它把左侧列表、选中 key 与关闭按钮都封装好了。但本系列的左侧是 5 列带选中态的网格,ListPage 的单列文本列表装不下这个结构;用它就得放弃网格,或者把网格塞进它的一行里,反而更绕。
所以最终方案只保留 Scroll。ListPage 与本篇的关系是「知道它存在、知道它不适用」,不是让读者在两个方案之间二选一。示例(五)(六)都沿本篇的 Scroll 继续。
运行效果
下面的 live 用 40 个假道具演示滚动效果:滚轮、右侧滚动条与「回到顶部 / 滚到底部」按钮都能用。live 用元素层等价画面实现滚动,正文代码块给出 Scroll 的真实写法;两者不是同一段代码。
边界与注意
Scroll里再包一层容器会让虚拟滚动失效。每一行都必须是Scroll的直接子元素。- 行容器的高度要包住整行格子;用默认 200×200 会让相邻行互相遮挡。
padEnd按行高调整。最后一行底部过紧或滚动条偏长时,先检查它。- 滚动条占右侧一段宽度,可点击元素不要压到
x = 372附近。 - 一维长列表用
Scroll;左右分栏的文本列表才考虑ListPage,固定页数才用Page。不要用几十个隐藏容器模拟分页。