跳到正文

VirtualList 虚拟列表

列表太长、没法一次全部渲染(几千行甚至更多)时用 VirtualList,比如聊天记录、日志、信息流,尤其是行高各不相同的时候。几百行以内时,把普通列表放进 ScrollArea 更简单;想把列表分页,请用 Pagination。

使用前须知
  • 列表自己就是滚动容器,高度取父元素的 height: 100%(max-height 也继承父元素),所以要把它放在有高度或 max-height 的容器里。
  • 把每一行收到的 style 展开到行的根元素上;开启 itemResizable 时,还要把 domRef 放在这个元素上,行才能被测量。

VirtualList 是一个高度可变的虚拟列表:只渲染视口里的行,行高在挂载时测量。

演示

基础用法

行高各不相同,挂载之前不知道。Scroll to index 和 Scroll to key 跳到指定的行;选一个 align 可以把它放在视口的顶部、中间或底部。

跳到某一行:align

scrollTo({ key, align })(或 index)把这一行的顶部放到视口顶部("start"),把它的中线放到视口中间("center"),或把它的底部放到视口底部("end"),都在 scrollMarginTop 和 scrollMarginBottom 以内。用默认的 behavior: "instant" 时,这一行会精确落位(误差 0 像素),而且不会画出任何别的位置,即使这一行和它周围的行从没测量过:

  • 浏览器绘制之前,列表先挂载目标行和填满它周围视口的行,同步测量它们(不等 ResizeObserver),按这一行在 DOM 里的真实位置算出精确的 scrollTop 并设置。如果这又让别的行进入视口,或者有行的尺寸变了(比如在自己的 layout effect 里长高的行),就再测一次,最多 10 次,通常两三次就稳定。离目标远的行保留估计高度:只有视口里的行需要精确。
  • 跳转后的一帧之内,ResizeObserver 报来的尺寸变化会重放这次跳转,和其他即时跳转一样。
  • 在两端位置会被夹住(最后一行到不了顶部)。
  • 用 behavior: "smooth" 时,列表按跳转开始时已知的布局滚动一次。

不传 align 时按这一行的估计偏移跳转:debounce(默认开启)时只滚到刚好能看见这一行,否则把这一行的顶部滚到估计的偏移处。以前要居中一行,得用滚动调整任务(submitScrollAdjustingTask)在每批测量之后挪一次,所以会先画出估计的位置再修正;align 取代了这种做法。

行的外边距

行可以随意使用外边距。行按普通的块级流排列,外边距按你的 CSS 折叠:相邻行之间会折叠,子元素的外边距也会穿过没有自己边框或内边距的行折叠,和普通列表完全一样。浏览器绘制之前,列表从布局中测出每一行实际占的空间(从这一行开始的位置到下一行开始的位置,包括折叠后的外边距),并按它摆放各行。第一行的上外边距和最后一行的下外边距会保留。行不需要 display: flow-root、gap 之类的处理。

随机高度

在前面或后面加行,改变视口里的行或所有行的高度。

在上方加行时保持顶部的行不动

开启 keepAnchorOnItemsChange 后,items 变化时视口顶部的那一行保持不动:在它上方插入或删除的行(比如在聊天开头加载更早的消息)不会让屏幕上的内容移动。点 Load 20 older,稍微滚动一下,再点 Remove 5 above 或 Remove the top row。关掉这个属性对比:那时保持的是滚动位置,行会被新加的行的高度往下推。

  • 默认关闭。 由代码在视口上方插入或删除行的列表才需要开启。
  • 滚到最顶部时同样生效。 列表在顶部时,原来的第一行保持原位,新行加在它上方、视口之外:加载更早的行不会把你正在看的内容挤走。设置了 paddingTop 时,留白只在第一行上方,所以前插之后原来留白的位置会露出上方最新一行的末尾。
  • 顶部的行被删除时, 它后面第一个仍然存在的行保持原位。如果从顶部那行开始往后的行全被删除,就保持滚动位置。
  • 跳转优先。 变化之前刚刚执行的即时 scrollTo(跳到某个 index、key、顶部或底部)照常执行。
  • 新行加在其下方的行可以用 canAnchorItem 排除:被它拒绝的行会像被删除的行一样跳过。适用于前插位置上方的开头行(标题、“历史开头”分界):让它保持不动会把正在读的行往下推。

不论是否开启这个属性,列表本身都会做两件相关的事:向上滚动时,视口上方的行第一次挂载并测量,和 itemEstimatedSize 的差会被滚动抵消,视口里的行不会跳动;已挂载、整行都在视口上方的行尺寸变化时(图片加载完、加了表情回应),变化也会被滚动抵消。被视口顶边切开的那一行不补偿:它有一部分在视口里。这只覆盖滚动和尺寸变化;keepAnchorOnItemsChange 覆盖 items 的变化。两者配合使用:前插的行在你向上滚到它们时被测量并得到补偿。

保留选中的行

有选中文字时,滚出视口的行不卸载,选区和复制仍然有效。先点 Select text in row 2,再点 Scroll to row 1000。

开关虚拟化

关闭虚拟化时所有行都渲染出来,视口顶部的那一行保持不动。

使用 ScrollArea 的滚动条

列表隐藏了原生滚动条。要在上面显示 ScrollArea 的浮动滚动条,用 useScrollAreaContainer 绑定列表自己的滚动元素:domRef 接 containerProps.ref,className 和 style 用容器的,<ScrollAreaGutters {...guttersProps} /> 通过 header 放进去,成为滚动元素的第一个子元素(见 ScrollArea)。列表照样自己滚动、测量和保持锚点。