虚拟滚动 | Quasar 中文网

虚拟滚动

QVirtualScroll 组件允许你仅显示长列表项的一部分，并在用户滚动容器时更新可见项目。这有几个优点：仅渲染可见项目，因此在任何给定时间点，DOM 树中的节点数量最少，内存消耗也保持在最低水平。

¥The QVirtualScroll component allows you to display only a part of a long list of items and update the visible items as the user scrolls in the container. This has several advantages: only visible items are rendered, so the smallest number of nodes are in the DOM tree at any given point in time and the memory consumption is kept at its lowest.

目前有两种类型的 QVirtualScroll：“list”（使用 QItems）和 “table”（使用表格样式显示数据行）。

¥There are currently two types of QVirtualScroll: “list” (using QItems) and “table” (using a tabular style to display rows of data).

用法(Usage)

¥Usage

提示

（Composition API）为了在使用大型列表时获得最佳性能，请勿使用 ref()/computed()/reactive() 等方法封装传入 items prop 的数组。这允许 Vue 跳过对列表 “responsive” 进行更改的步骤。
¥(Composition API) To get the best performance while using large lists, do not wrap the array that you are passing in the items prop with ref()/computed()/reactive()/etc. This allows Vue to skip making the list “responsive” to changes.
（Options API）为了在使用大型列表时获得最佳性能，请使用 Object.freeze(items) 冻结传入 items 属性的数组。这使得 Vue 可以跳过列表 “responsive” 的更改。
¥(Options API) To get the best performance while using large lists, freeze the array that you are passing in the items prop using Object.freeze(items). This allows Vue to skip making the list “responsive” to changes.
将根据 virtual-scroll-item-size 属性和可滚动区域的大小计算渲染的项目数量，但你可以使用 virtual-scroll-slice-size 属性来调整以满足你的需求。
¥The number of items that will be rendered will be calculated based on the virtual-scroll-item-size prop and the size of the scrollable area, but you can fit it to your needs using the virtual-scroll-slice-size prop.
使用 virtual-scroll-item-size 属性指定元素的大小（高度像素，如果是水平方向则为宽度）。元素在屏幕上渲染后，其大小会自动更新，但如果你指定一个接近实际大小的元素大小，你将获得更好的滚动位置初始指示。无论你是否使用此属性，QVirtualScroll 仍然可以工作，但如果没有它，你可能会遇到滚动条在连续滚动（桌面端）时不跟随鼠标抓取位置的情况，或者在移动设备上连续滚动时，容器的实际滚动会稍微偏离一个或两个元素的情况。
¥Use the virtual-scroll-item-size to specify the size of elements (pixels of height, or width if horizontal). After an element is rendered on screen its size is updated automatically, but if you specify an element size close to the real size you’ll get a better initial indication of the scroll position. Regardless if you will be using this property or not, QVirtualScroll will still work, but without it you may experience the scrollbar not following the mouse grab position while continuously scrolling (on desktop) or the actual scroll of the container getting slightly off by one or two elements when on mobile and continuously scrolling.

警告

每个浏览器都规定了滚动容器的最大高度。在 IE11 中，这个值大约是 1,000,000px，而在其他浏览器中，这个值要大得多，但仍然有限。

¥There is a maximum height of the scrolling container, imposed by each browser. In IE11 this is around 1,000,000px, while in the rest of the browsers it’s much more, but still limited.

滚动下方示例，查看 QVirtualScroll 的实际运行情况。

¥Scroll the examples below to see QVirtualScroll in action.

基本(Basic)

¥Basic

水平(Horizontal)

¥Horizontal

不同模板(Different templates)

¥Different templates

表格类型(Table type)

¥Table type

注意 type="table" 属性。

¥Notice the type="table" property.

标题会随内容滚动（不会停留在原地）。

¥With header that scrolls along with content (doesn’t stay in place).

请注意（在下面的示例中）将表格页眉和页脚设置为 “sticky” 所需的 CSS。另请注意定义页眉和页脚内容的附加作用域插槽。

¥Notice (in the example below) the CSS required to make the table header and footer “sticky”. Also note the additional scoped slots which define the header and footer content.

下面是一个更复杂的示例，使用粘性页眉和页脚。

¥A more involved example below, playing with sticky headers and footers.

滚动目标(Scroll target)

¥Scroll target

如果你需要指定滚动目标（因为自动检测到的目标不是所需的目标），请将 CSS 选择器（字符串形式）或 DOM 元素传递给 scroll-target 属性。

¥If you need to specify the scroll target (because the auto detected one is not the desired one) pass a CSS selector (as string) or the DOM element to the scroll-target prop.

如果你需要使用虚拟列表并将整个页面作为滚动元素，请设置 scroll-target="body"。

¥If you need to use the virtual list with the whole page as the scrolling element then please set scroll-target="body".

警告

如果你传递带有 scroll-target 属性的自定义滚动目标容器，则必须确保该元素存在并且可以溢出（它必须具有最大高度和允许滚动的溢出）。
¥If you pass a custom scroll target container with scroll-target prop you must make sure that the element exists and that it can be overflowed (it must have a maximum height and an overflow that allows scrolling).
如果滚动目标容器无法溢出，你将渲染整个列表。
¥If the scroll target container cannot be overflowed you’ll get the whole list rendered.

危险

如果你想为 scroll-target 使用 Vue 引用，请在挂载组件后小心设置，如下例所示。

¥If you want to use a Vue reference for scroll-target, please take care to set it after mounting the component, like in the example below.

滚动到位置(Scroll to position)

¥Scroll to position

同步和异步(Sync and async)

¥Sync and async

你还可以使用 items-fn 属性生成要在列表中显示的项目。

¥You can also generate the items to be displayed on the list by using the items-fn prop.

警告

请确保使用同步函数返回要显示的项目列表。

¥Make sure to use a synchronous function that returns the list of items to be displayed.

如果你需要异步数据，请使用一个组件来检索和渲染数据。

¥If you need async data use a component that retrieves and renders the data.

实用程序类(Utility classes)

¥Utility classes

你可以使用两个 CSS 类（如果需要）来控制 VirtualScroll 大小的计算：

¥There are two CSS classes that you can use (should you need to) to control VirtualScroll size calculation:

在 VirtualScroll 渲染的元素上使用 q-virtual-scroll--with-prev 类，以指示该元素应与前一个元素分组（主要用例是从同一行数据生成的多个表格行）。
¥Use q-virtual-scroll--with-prev class on an element rendered by the VirtualScroll to indicate the element should be grouped with the previous one (main use case is for multiple table rows generated from the same row of data).
在 VirtualScroll 渲染的元素上使用 q-virtual-scroll--skip 类，以指示在大小计算中应忽略元素大小。
¥Use q-virtual-scroll--skip class on an element rendered by the VirtualScroll to indicate the element size should be ignored in size calculations.

1. Introduction

2. QVirtualScroll API

3. 用法(Usage)

3.1. 基本(Basic)

3.2. 水平(Horizontal)

3.3. 不同模板(Different templates)

3.4. 表格类型(Table type)

3.5. 滚动目标(Scroll target)

3.6. 滚动到位置(Scroll to position)

3.7. 同步和异步(Sync and async)

3.8. 实用程序类(Utility classes)