# 示例(四)滚动与列表 道具少的时候,网格一次就能排下。道具变多后,左侧区域放不下,需要滚动。本篇把示例(二)的普通网格换成 `Scroll`,并说明这次替换在渲染树、事件与数据流上各自改了什么。 ## 前置知识 阅读本篇前,建议先读完: - [示例(三)详情区](./inventory-example-3-detail.md) - [内置组件:布局](./builtin-layout.md) ## 为什么要换滚动 普通容器只是按坐标把子元素画出来:区域外的格子照样绘制,超出的部分被窗口裁掉,但节点仍然在树上。道具只有十件时感觉不到问题;四十件时,左侧区域外的格子会越画越多,滚轮也没有任何反应。 `Scroll` 负责的是「视口」这一层: - 它给内容一个固定大小的窗口,窗口外的行被隐藏(逻辑裁剪),不会继续绘制。 - 它自己处理滚轮、拖动与右侧滚动条,不需要作者再写 `onWheel`。 - 它按子元素的包围盒计算可滚动总长度,末尾用 `padEnd` 补一段空白。 代价是限制:`Scroll` 只检查它的**直接子元素**,所以内容不能先包一个大容器再放进去。一个把全部格子包住的 `ItemGrid` 根容器会让虚拟滚动退化成「一整块内容」,只能整体显示或整体隐藏。 组件本身不是节点(第 13 篇):`ItemGrid` 返回的是行数组,这些行会平铺成父级 `Scroll` 的直接子元素,而不是躲在组件内部;所以行容器能被 `Scroll` 直接读到,虚拟滚动成立。 **本步明确替换示例(二)的普通网格**:左侧最终方案是 `Scroll`,示例(五)(六)不会再回到普通网格或 `ListPage`。 ## Scroll 在渲染树里的位置 替换后,左侧区域的树是这样: ```text 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()` 拿到的就是这个接口,只有在需要「回到顶部 / 滚到底部 / 滚到某一行」时才用它。 ## 数据与选中态如何穿过滚动层 `Scroll` 只负责视口,不持有道具数据,也不持有选中状态: - `items` 仍然是 `InventoryPanel` 里的 `ref`,由面板传给 `ItemGrid`。 - `selectedId` 仍然是面板的 `ref`,由 `ItemGrid` 继续按 id 比较。 - `ItemGrid` 的 props 链不变:`items` / `selectedId` / `onSelect`(示例(五)再加 `equippedId`)。 唯一要改的是 `ItemGrid` 的根节点:示例(二)里它返回一个 `container`,现在改成返回「行容器数组」,让每一行直接成为 `Scroll` 的直接子元素。组件本身仍然是一个组件,只是它的子树从「一个容器」变成了「一组并列容器」: ```tsx // 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 决定 {cells.map((item, col) => ( emit('select', id)} /> ))} ); } return rows; }; }, itemGridProps); ``` 行容器的 `key` 用行号,是因为行本身没有业务身份,只表示「第几行」;行内的格子 `key` 仍然用 `item.id`,身份跟道具走。滚动时 `Scroll` 按行容器的包围盒决定整行显示还是隐藏,所以一行的高度必须包住这一行的格子,不能只给格子高度却让行容器用默认 200×200。 ## 面板里怎么接 面板把 `ItemGrid` 放进 `Scroll`,其余状态不变: ```tsx import { ref } from 'vue'; import { Scroll, ScrollExpose } from '@user/client-base'; // 面板里:滚动容器只包住网格,选中态仍由面板持有 const scroll = ref(); // 回到顶部:scrollTo(目标位置, 动画时长) const backToTop = () => { scroll.value?.scrollTo(0, 200); }; // 滚到底部:先取总长度,再滚过去 const toBottom = () => { scroll.value?.scrollTo(scroll.value.getScrollLength(), 200); }; (selectedId.value = id)} /> ; ``` `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`。不要用几十个隐藏容器模拟分页。