Vue虚拟列表插件vue-virtual-scroller之中文文档

vue-virtual-scroller是一个高度可定制的虚拟滚动列表插件，它可以在大量数据下提供高性能的渲染和滚动。它可以处理各种类型的数据，例如列表、表格、瀑布流等，并且支持水平和垂直滚动，也支持动态列表项。vue-virtual-scroller的API和事件系统也非常丰富，可以让开发者轻松地自定义滚动逻辑和交互效果。

支持 Vue2，Vue3。

安装

npm install --save vue-virtual-scroller

默认导入

安装所有组件：

import Vue from 'vue'
import VueVirtualScroller from 'vue-virtual-scroller'

Vue.use(VueVirtualScroller)

使用指定组件：

import Vue from 'vue'
import { RecycleScroller } from 'vue-virtual-scroller'

Vue.component('RecycleScroller', RecycleScroller)

导入样式：

import 'vue-virtual-scroller/dist/vue-virtual-scroller.css'

使用

vue-virtual-scroller 插件提供了多个组件：

RecycleScroller 是一个用来渲染列表可见的 items 的组件。它会复用组件和元素尽可能的使其高效和高性能。

DynamicScroller 是一个用来包裹 RecycleScroller 的组件，它扩展它的它的特性用来管理动态尺寸。它的主要使用场景是你提前不知道 items 的尺寸。当发生滚动渲染新 item 的时候，DynamicScroller 组件会自动发现他们的尺寸。

DynamicScrollerItem 必须包裹每个 item 在 DynamicScroller 里的时候，用来计算 item 尺寸。

RecycleScroller

基本使用

<template>
  <RecycleScroller
    class="scroller"
    :items="list"
    :item-size="32"
    key-field="id"
    v-slot="{ item }"
  >
    <div class="user">
      {{ item.name }}
    </div>
  </RecycleScroller>
</template>

<script>
export default {
  props: {
    list: Array,
  },
}
</script>

<style scoped>
.scroller {
  height: 100%;
}

.user {
  height: 32%;
  padding: 0 12px;
  display: flex;
  align-items: center;
}
</style>

重要提示

• 你必须设置虚拟滚动容器和内部 item 的尺寸。除非你使用多尺寸模式，所有的 items 必须设置相同的高度，以免出现差错。
• 如果 item 数据是一个对象，滚动容器必须能标识它们。默认使用 id 字段，也可以使用 keyField 属性配置为其他字段。
• 因为组件会被复用，RecycleScroller 里不推荐使用函数式组件（反之实际上会更慢）。
• The list item components must be reactive to the item prop being updated without being re-created (use computed props or watchers to properly react to props changes!).
• 你不需要给列表内容设置 key（但你必须给所有嵌套的 <img> 元素设置 key 以免发生下载错误）。
• 浏览器有最大元素数量限制，它意味着目前虚拟列表 items 最大显示数量不能超过 500k。
• 由于 items 的dom元素是复用的，所以推荐使用组件提供的 hover class 来定义 hover 样式来代替 :hover 选择器（e.g. .vue-recycle-scroller__item-view.hover or .hover .some-element-inside-the-item-view）。

props

• items：列表要显示的数据
• direction: 滚动方向（默认 vertical），可选：vertical、horizontal
• itemSize：默认 null。item 的高度，用来计算滚动列表的高度和位置。如果设置为 null，则会使用多尺寸模式。
• gridItems
• itemSecondarySize
• minItemSize：当一个 item 的高度未知时可以设置最小尺寸。
• sizeField：默认 size。多尺寸模式下 item 尺寸保存在 item 数据的哪个字段里。
• typeField：默认 type。用于区分列表中不同类型的组件。每种不同的组件，都会创建一个循环的 items。
• keyField：默认 id。用于标识 items 和优化渲染视图。
• pageMode：默认 false。是否开启 Page mode 模式。
• prerender：默认 0。服务端渲染时，渲染 items 的数量。
• buffer：默认 200。在列表外额外要多渲染的 px 数。
• emitUpdate：默认 false。是否在每次列表容器内容更新后发送 update 事件（会影响性能）。
• listClass：给列表容器添加自定义 class。
• itemClass：给每个 item 添加自定义 class。
• listTag：默认 div。列表容器要渲染成的元素标签。
• itemTag：默认 div。item 要渲染成的元素标签（默认插槽的直接父元素）。

Events

• resize：列表容器尺寸改变时触发。
• visible：列表容器在页面显示时触发。
• hidden：列表容器在页面隐藏时触发。
• update (startIndex, endIndex, visibleStartIndex, visibleEndIndex)：每次视图更新时触发，前提是 emitUpdate 属性要设置为 true。
• scroll-start：第一个 item 渲染后触发。
• scroll-end：最后一个 item 渲染后触发。

默认插槽 props

• item
• index
• active

其它 Slots

<main>
  <slot name="before"></slot>
  <wrapper>
    <!-- Reused view pools here -->
    <slot name="empty"></slot>
  </wrapper>
  <slot name="after"></slot>
</main>

Page Mode

Page Mode 下，组件会根据网页视口自动计算要显示哪些 items。设置 page-mode 属性为 true：

<header>
  <menu></menu>
</header>

<RecycleScroller page-mode>
  <!-- ... -->
</RecycleScroller>

<footer>
  Copyright 2017 - Cat
</footer>

多尺寸模式

这个模式会使性能变重。请谨慎使用！

当 itemSize 属性没有设置或者设置为 null 后，虚拟列表会切换为多尺寸模式。你需要在 item 数据里给每个 item 设置一个尺寸。

const items = [
  {
    id: 1,
    label: 'Title',
    size: 64,
  },
  {
    id: 2,
    label: 'Foo',
    size: 32,
  },
  {
    id: 3,
    label: 'Bar',
    size: 32,
  },
]

DynamicScroller

工作原理跟 RecycleScroller 类似，但是它可以渲染尺寸未知的 items。

详情请见官方文档。